[h-e-w] Merging Win32 documentation with Emacs main docs

[David Vanderschel]

On Thursday, July 13, "Eli Zaretskii" <address@hidden> wrote:
> From: David Vanderschel <address@hidden>

>> What I perceive as a forking of this sort of
>> information is the Win32 stuff to be found in the
>> Emacs Wiki.

>That, too, is a less than efficient use of our scarce resources, IMHO.

It has occurred to me that folks who contribute to the
Wiki should be encouraged to reference material in the
official manual and/or FAQ _whenever_ there is
relevant documentation in either.  (I.e., avoid
duplication if at all possible and treat the
documentation at the gnu.org site as authoritative.)
To facilitate this, it would be helpful if the current
FAQ could be accessed as HTML on the gnu.org site.
There exist utilities to render an Info file as HTML,
so this should be straightforward.  Unfortunately, at
present I do not know where to find an HTML version of
the current FAQ on the Web.  (The manual is already
presented in HTML and it is replete with a high
density of named anchor tags, so referencing
subsections of it is no problem.  I cannot figure out
why this was not done for the FAQ as well.  The plain
text FAQ is pretty ugly by comparison - and it is not
as useful for lack of live links.)

When useful documentation appears in the Wiki and that
documentation has no counterpart in the existing
official documents, then it strikes me that there
should be an effort to migrate that documentation into
the official gnu.org tree after which it can be
accessed by reference from the Wiki.

>> This is the first call I have seen to completely
>> abandon the Windows FAQ.  If the problem is that it
>> contains information which is no longer necessary or
>> relevant, then cleaning the junk out should not be
>> such a problem.

>But why do that at all?  We already have a FAQ in Emacs, let's
>maintain the information in one piece, in one document.

>> It appears that Eli is advocating
>> merging what's left into the regular Emacs FAQ.

>Yes!

Actually, this sounds reasonable to me.  If we can
agree that something along these lines is the
objective, then we could hope for a volunteer or two. 
Any of our "scarce resources" listening?

What powers need to rule that someone representing the
Windows port of Emacs should be allowed to work on the
the official Emacs FAQ?  I don't know how such efforts
are managed.

Could it not be that some of the useful Windows-
specific stuff should really go in the manual?

>> What
>> concerns me about this is that the regular Emacs FAQ
>> seems to be even farther out of date than the Windows
>> FAQ.  We could be talking about different things; but
>> what I know to be the "Emacs FAQ" may be found here:
>> http://www.gnu.org/software/emacs/emacs-faq.text
>> And it says, "This is the GNU Emacs FAQ, last updated
>> on 26 October 2001."

>That's because the FAQ on the gnu.org site is for the _released_
>version of Emacs; it will be updated when Emacs 22.1 will be released.

For the sake of those who contribute to the Emacs
Wiki, it might be useful to have the development
version accessible for cases in which the new one
contains useful documentation that the current one
does not.  That would also help ease the transition
when the new version is released.  (It would also
provide more eyes to note problems with the version
under development.)

I have my doubts about whether the FAQ on the Emacs
Web site at gnu.org is current with the manual there.
The manual says "it corresponds to GNU Emacs version
22.0.50."  Regarding current released version, the
Emacs page says "21.4 (stable) released on
2005-11-05".  The FAQ says "last updated on 26 October
2001".  None of these are consistent.  It appears that
the manual is newer than the current stable version
and that the FAQ is much older.

>But the up-to-date version of the FAQ comes with the Emacs
>distribution, since the Emacs FAQ is part of the distributed Info
>files.  What do you care about outdated versions on the Web if you
>have the latest and greatest at your fingertips?  

I don't.  But I am still running v20.7 which was not
even distributed with an Info file for its FAQ.  (It
does have a plain text FAQ file.)

In any case, I have argued, in the spirit of avoiding
duplication of effort, that up-to-date (and even
anticipated) versions of both the manual and the FAQ
should be available on the gnu.org Web site so that
relevant portions of these official documents can be
cited from the Wiki.

Regards,
  David V.