Re: F-O-M (was: Patch for old FAQ links)

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On Fri, 26 Jan 2001, Gerald Pfeifer wrote:

> On Wed, 27 Dec 2000, Jeffrey A Law wrote:
> > If the world at large isn't contributing anything useful, then it seems to
> > me like FOM isn't worth the maintenance burden and we should go back to a
> > static web page like we had before.
> >
> > I haven't looked at it closely, so I'll leave that decision to y'all.
> 
> Joseph, you probably missed that one. I agree with Jeff, and as you've
> been the one checking/cleaning the FOM lately, I think you're perfectly
> qualified to make a founded recommendation.

My view is:

* We should use a FAQ maintained in CVS through submission of patches to
gcc-patches.

* The FAQ could be one monolithic file (as with the old faq.html), or one
file per section, or one file per question.  With the latter two, some
scripts should be used to maintain a single-file form of the FAQ and to
maintain indexes to it.  The advantages of one file per question are (a)
that redirection of accesses to the URL to that question are easier (see:
the problem that the server can't redirect faq.html#bugreport to
bugs.html), and (b) that obsolete questions (relevant only to old GCC
versions) can be excluded from the FAQ index without breaking links to
them.

* This way, we get accessible version history.  (I understand that the FOM
maintains some version history, but it isn't accessible to FOM users.)

* With static web pages, we can also be sure that the FSF owns the
copyright on the FAQ it includes with releases, and has the right to
distribute it.  If this is important, migration would need to be starting
from the final static faq.html and examining the FOM version history,
checking that any significant changes are by people with copyright
assignments.

* The division between what goes on the web pages and what goes in the
Texinfo manual should be clearly documented.  I suggest the following:

 + Documentation relating to the features and use of a specific version of
 GCC should go in the Texinfo manual (and so branch for releases).  
 Exception: the current practice is for installation instructions to go on
 the web pages, even though they ought logically to relate to a particular
 version and branch for releases.

 + Documentation relating to the GCC project, which does not meaningfully
 branch for releases, should go on the web pages.

 + Documentation likely to need updating after a release should go on the
 web pages.  This includes the FAQ, notes on installation problems on
 particular systems, and details of known bugs (which should go in GNATS,
 possibly on the projects pages if interesting, and in the known bugs list
 and possibly the FAQ if frequently reported; the lists of known bugs in
 the manual should be migrated).  However, documentation of known
 limitations of a particular version can go in the manual.

 + Some existing documentation may be in the wrong place.  Such
 documentation should be migrated over time.

-- 
Joseph S. Myers
jsm28@cam.ac.uk