Procedure for changing the FAQ

Procedure for changing the FAQ

[Glenn Morris]

Updating the FAQ is an etc/TODO item. Is there any kind of procedure
to be followed for this?

I assume one can just go ahead and update any old URLs, package
versions, etc.

But what about more drastic changes? For example, I think the "Emacs
Lisp Archive" is long dead, so I would propose to delete all
references to that and replace them with the "Emacs Lisp List" (and/or
the Wiki), which I think is the best current source for Emacs
packages. But others might not agree with me.

What about adding new FAQs? Does any kind of consensus have to be
reached on what constitutes a FAQ? Similarly, should some kind of
discussion as to what is the best answer to any given FAQ take place?

I would guess that, in an ideal world, the answers to those questions
would be yes, and yes; but that in practice perhaps not...

Basically, my question is: is it OK to make non-trivial changes to
the FAQ without discussion?

Is man/faq.texi even the master copy of the FAQ or not? It refers to
emacs-faq@lerner.co.il as the FAQ maintainers. But the version at
http://www.lerner.co.il/emacs (which describes itself as the "home of
the GNU Emacs FAQ", and is linked to from
http://www.gnu.org/software/emacs/) refers to version 20.4 as the
current version!

Re: Procedure for changing the FAQ

[Eli Zaretskii]

> From: Glenn Morris <gmorris+mail@ast.cam.ac.uk>
> Date: Tue, 22 Apr 2003 16:45:07 +0100
> 
> Updating the FAQ is an etc/TODO item. Is there any kind of procedure
> to be followed for this?

Nothing special, the FAQ is just another part of the Emacs
documentation.  Treat it as you would anything else in the `man'
subdirectory.

> I assume one can just go ahead and update any old URLs, package
> versions, etc.

Yes, that's one thing that needs to be done occasionally.

> But what about more drastic changes? For example, I think the "Emacs
> Lisp Archive" is long dead, so I would propose to delete all
> references to that and replace them with the "Emacs Lisp List" (and/or
> the Wiki), which I think is the best current source for Emacs
> packages. But others might not agree with me.

If no one disagrees, please go ahead and do this.  However, it might
be a better idea to leave the reference to the archive and say that
it was not updated in years.

> What about adding new FAQs?

Yes, please!

> Does any kind of consensus have to be reached on what constitutes a
> FAQ?

Searching gnu.emacs.help and counting the number of times a question
was asked will do, I guess.  Asking here will also help, as several
maintainers do read gnu.emacs.help and have some idea about what's
asked frequently.

> Similarly, should some kind of
> discussion as to what is the best answer to any given FAQ take place?

I think it's a good idea to run the answer by this list.

> Basically, my question is: is it OK to make non-trivial changes to
> the FAQ without discussion?

It's okay to do that, yes.  Personally, I don't recommend that, but
I'm known to disagree on this with others, and I cannot call myself an
active developer lately, so my opinions hardly matter too much.

> Is man/faq.texi even the master copy of the FAQ or not?

Yes.

> It refers to emacs-faq@lerner.co.il as the FAQ maintainers.

As the Copyright line shows, Reuven Lerner does not maintain the FAQ
actively for a few years now; we do.  You will see in "cvs annotate"
that many non-trivial changes were done by us in the FAQ over the last
years.

Re: Procedure for changing the FAQ

[Stefan Monnier]

...about the FAQ...

I think the FAQ has generally not been maintained very well for the simple
reason that such FAQs should be addressed by the manual rather than
by a FAQ.  Admittedly, the way it's presented is different, so there's
some sense to having a FAQ additionally to the manual, but please think
of it as another kind of index to the manual: most answers should @xref
to the relevant part of the manual.  If there's no such thing in the
manual, then the manual needs to be updated.

Of course the FAQ should probably not contain only @xref because people
will find it obnoxious, so at least the core part of the answer should
be present additionally to the @xref.

That's my personal opinion anyway, I have no idea what others think about it.


	Stefan

Re: Procedure for changing the FAQ

[Frank Schmitt]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> writes:

> I think the FAQ has generally not been maintained very well for the simple
> reason that such FAQs should be addressed by the manual rather than
> by a FAQ.  Admittedly, the way it's presented is different, so there's
> some sense to having a FAQ additionally to the manual, but please think
> of it as another kind of index to the manual: most answers should @xref
> to the relevant part of the manual.  If there's no such thing in the
> manual, then the manual needs to be updated.

I partly disagree, partly agree. First of all, the main documentation
is huge and the answers to the questions especially newbies have are
often in sections where they wouldn't expect them.

Therefor a FAQ should explain all major concepts, but concentrate on
the most important parts (e.g. only mention the most often used command
switches) while referring to the manual for more details. However, the
informations contained should be sufficient to get you running with a
basic setup.

It's hard to explain, perhaps you throw an eye at
http://my.gnus/org/FAQ where I tried to make a FAQ that meets my idea
of a good one to see what I'm talking about. 

(BTW: This shows that it isn't this much work, the FAQ contains at the
moment 68 question - answer pairs and the text version has about 1,600
lines and it took me all together only about 2-3 weeks to write it from
scratch)

MFG Frank

-- 
WANTED: A nice signature
REWARD: none

Re: Procedure for changing the FAQ

[Eli Zaretskii]

> From: Frank Schmitt <ich@Frank-Schmitt.net>
> Date: Wed, 23 Apr 2003 16:08:25 +0200
> 
> I partly disagree, partly agree. First of all, the main documentation
> is huge and the answers to the questions especially newbies have are
> often in sections where they wouldn't expect them.

That's what the indexing is for, and the `i' command inside Info.  We
should educate users to use that much more than they do, and we should
strive to make our indexing even better.

> Therefor a FAQ should explain all major concepts

I disagree: I think explaining major concepts is something the FAQ
should _not_ do; they are already explained in the manual.

Yes, I know many computer users are used to look in the FAQ before
they look in the manual, but I think we should convince Emacs users
that's not the right way of looking something up in the docs.

Re: Procedure for changing the FAQ

[Alex Schroeder]

"Eli Zaretskii" <eliz@elta.co.il> writes:

> Yes, I know many computer users are used to look in the FAQ before
> they look in the manual, but I think we should convince Emacs users
> that's not the right way of looking something up in the docs.

I used to (silently) disagree with Eli on this one, but these days I
agree.  If people have questions they need answers to, and they can't
find it in the manual, then the manual needs to be changed.  Maybe new
text needs to be written, or maybe new features need to be added.  The
index search is a prime example.  It is very powerful, and I only
learnt about it years after starting to use Emacs.  The glossary is
another example, if I remember correctly it was added because people
using Microsoft terms were unable to find the correct information in
the manual.  Perhaps we need "dedicated" pages in the manual.  Mail
setup.  Indentation.  Just to name the two most commonly asked
questions on #emacs.  :)

The wiki tries to do this kind of thing, of course, but by its very
nature the pages have varying levels of quality, and include personal
assessments of various solutions.  This is a good thing, and a new
thing that was not possible before, but it also means that you cannot
just take text from the wiki and incorporate it into the manual.

Perhaps the wiki is an interesting collection of loosely organized
information so that we could pack it into a texinfo file and
distribute it the same way we used to distribute the manuals in the
old days...  That might be an interesting alternative.

The wiki is licensed under the FDL, but no copyright assignments were
required of contributors.  There used to be a script that translated
the entire site to a texinfo file, but it needs updating.  Bitrot.  :)

Alex.

Re: Procedure for changing the FAQ

[Eli Zaretskii]

> From: Alex Schroeder <alex@gnu.org>
> Date: Thu, 24 Apr 2003 00:31:22 +0200
> 
> Perhaps we need "dedicated" pages in the manual.  Mail
> setup.  Indentation.  Just to name the two most commonly asked
> questions on #emacs.  :)

Mail setup already has its own manual, added recently to the CVS.  As
for indentation, that part of the manual was completely rewritten by
Richard some time ago, with the explicit purpose of making it more
clear, so perhaps you could take a look at it and see what else needs
to be improved there.

> Perhaps the wiki is an interesting collection of loosely organized
> information so that we could pack it into a texinfo file and
> distribute it the same way we used to distribute the manuals in the
> old days...

The wiki is certainly one place where to look for possible additions
to the FAQ, especially if there's a way to know how many times each
issue was hit by netsurfers.

Re: Procedure for changing the FAQ

[Kai Großjohann]

"Eli Zaretskii" <eliz@elta.co.il> writes:

> Mail setup already has its own manual, added recently to the CVS.  As
> for indentation, that part of the manual was completely rewritten by
> Richard some time ago, with the explicit purpose of making it more
> clear, so perhaps you could take a look at it and see what else needs
> to be improved there.

Ah, indeed.  The new chapter on indentation looks quite different.  I
like it.

I suggest to mention the different alternatives more clearly, though.
Take tab-to-tab-stop as an example.  It is mentioned on the first page
(in (emacs)Indentation), but not explained there.  It's then explained
in detail in the tab stops section (in (emacs)Tab Stops).

WIBNI there was a summary that said that there are three (four if you
count self-insert-command) different methods available, to explain
when and why they are used, and then to explain each in detail, as is
done now?  (The methods are tab-to-tab-stop, indent-relative, and
syntax-driven indentation.)

The explanation on syntax-driven indentation should mention
customizability in a prominent place.  I think it is important to say
that because people often shy away from it just because Emacs
"indents wrong" in the default setting.  It should also give pointers
to explanations on configuring syntax-driven indentation for some
popular modes (at least a pointer to (ccmode)Customizing Indentation).

Ok to fix?
-- 
file-error; Data: (Opening input file no such file or directory ~/.signature)

Re: Procedure for changing the FAQ

[Richard Stallman]

    Ah, indeed.  The new chapter on indentation looks quite different.  I
    like it.
    ...

    Ok to fix?

Please do give it a try.

Re: Procedure for changing the FAQ

[Kai Großjohann]

Richard Stallman <rms@gnu.org> writes:

>     Ok to fix?
>
> Please do give it a try.

Here is my first attempt.  The wording is awful, but I hope it shows
the general direction that I meant.  Writing documentation is quite
hard!

If the direction is okay, I'll sleep over it and try to come up with
something more coherent.

Should there be a special `overview' section?

Should the overview come before or after the list of keys?

(Note that TAB in fundamental mode and text mode now runs
indent-relative, the following patch reflects that.  Not sure if the
remark about TAB in indented text mode in the following node needs to
be changed.)

(Regarding the list of keys the node Indentation, I think that `do
like TAB on each line' is a better description of indent-region.  Most
of the time, it does NOT indent all of the lines to the same column ;-)

--- indent.texi.~1.11.~	Wed Feb  5 20:46:31 2003
+++ indent.texi	Sat Apr 26 23:10:18 2003
@@ -35,10 +35,56 @@
 Indent from point to under an indentation point in the previous line.
 @end table
 
+  Emacs supports four general categories of operations that could all
+be called `indentation':
+
+@enumerate
+@item
+The most simple operation is to just insert a tab character.  This
+operation does not have a convenient key binding, because it is
+subsumed by the more general operation described next.  But you can use
+@kbd{C-q @key{TAB}} to insert a literal tab character.
+
+A tab character is displayed as a stretch of whitespace which extends
+to the next display tab stop position, and the default width of a tab
+stop is eight.  @xref{Display Custom}, for more details.
+
+@item
+Emacs also supports tab stops.  You can set them at arbitrary
+positions, and then use @kbd{M-i} to advance to the next tab stop.  The
+default tab stop list contains positions (columns) that are a multiple
+of eight, and so the effect of @kbd{M-i} is the same as that of
+@kbd{C-q @key{TAB}} in the default case.
+
+You can set the tab stops with @kbd{M-x edit-tab-stops}.
+
+@item
+You can align successive lines with each other.  This is called
+@dfn{relative indentation} in Emacs and is performed by the command
+@kbd{M-x indent-relative}.  The effect is best shown by an example:
+@example
+This shows the effect of relative indentation.
+^    ^     ^   ^      ^  ^        ^
+@end example
+The positions for the @code{^} characters on the second line were
+obtained using @kbd{M-x indent-relative}.
+
+In Fundamental mode and in Text mode, @key{TAB} runs the command
+@code{indent-relative}.
+
+@item
+The most sophisticated method is called @dfn{syntax-driven indentation}
+and is the default behavior of the @key{TAB} key in Emacs.
+
   Most programming languages have some indentation convention.  For Lisp
 code, lines are indented according to their nesting in parentheses.  The
 same general idea is used for C code, though many details are different.
 
+  For some languages, different kinds of indentation styles are
+commonly used.  Emacs accomodates this by allowing users to customize
+the indentation.  For example, see @ref{Customizing Indentation,,,ccmode},
+for a description of these facilities for the C language.
+
 @kindex TAB
   Whatever the language, to indent a line, use the @key{TAB} command.  Each
 major mode defines this command to perform the sort of indentation
@@ -48,9 +94,11 @@
 mode, @key{TAB} implements a subtle and sophisticated indentation style that
 knows about many aspects of C syntax.
 
-  In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
-indents to the next tab stop column.  You can set the tab stops with
-@kbd{M-x edit-tab-stops}.
+@end enumerate
+
+@c   In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
+@c indents to the next tab stop column.  You can set the tab stops with
+@c @kbd{M-x edit-tab-stops}.
 
   Normally, @key{TAB} inserts an optimal mix of tabs and spaces for
 the intended indentation.  @xref{Just Spaces}, for how to prevent use

-- 
file-error; Data: (Opening input file no such file or directory ~/.signature)

Re: Procedure for changing the FAQ

[Richard Stallman]

    +@enumerate
    +@item
    +The most simple operation is to just insert a tab character.  This
    +operation does not have a convenient key binding, because it is
    +subsumed by the more general operation described next.  But you can use
    +@kbd{C-q @key{TAB}} to insert a literal tab character.
    +
    +A tab character is displayed as a stretch of whitespace which extends
    +to the next display tab stop position, and the default width of a tab
    +stop is eight.  @xref{Display Custom}, for more details.
    +
    +@item
    +Emacs also supports tab stops.  You can set them at arbitrary
    +positions, and then use @kbd{M-i} to advance to the next tab stop.  The
    +default tab stop list contains positions (columns) that are a multiple
    +of eight, and so the effect of @kbd{M-i} is the same as that of
    +@kbd{C-q @key{TAB}} in the default case.
    +
    +You can set the tab stops with @kbd{M-x edit-tab-stops}.

There is too much detail about specific commands.  Those
belong later (and are already included later).  What we need here
is just the concepts, and maybe cross references.

For instance, when explaining tab stops, there is no need to talk about
the default tab stops.  That is just a detail, and this is not the
place for details.

    +The most simple operation is to just insert a tab character.  This
    +operation does not have a convenient key binding, because it is
    +subsumed by the more general operation described next.
    ...
      The
    +default tab stop list contains positions (columns) that are a multiple
    +of eight, and so the effect of @kbd{M-i} is the same as that of
    +@kbd{C-q @key{TAB}} in the default case.
    +

This is simple and convenient in practice, but your description makes
it sound like something bad.  Here's how to describe the situation and
show how it is convenient.

  The simplest kind of indentation operation is to insert a space or
  tab.  You can insert a tab by typing C-q TAB.  With the default tab
  stops, M-i also does this.

This sort of mention of M-i seems appropriate here, because it
involves less detail than the one I criticized.

Re: Procedure for changing the FAQ

[Richard Stallman]

    I partly disagree, partly agree. First of all, the main documentation
    is huge and the answers to the questions especially newbies have are
    often in sections where they wouldn't expect them.

When you come across a question that newbies have difficulty finding
in the manual, please report that.  Independent of whatever work we
do on the FAQ, we would like to improve the manual.

Re: Procedure for changing the FAQ

[Glenn Morris]

"Stefan Monnier" wrote:

[comments]


OK, so it seems to me that you are saying:

Most of the info in any FAQ should be in the manual.

The FAQ should refer to the manual, but also function on its own at
some level.

The FAQ should act as another entry point to the manual.


I would agree with all those points. I'd say a FAQ is for a (slightly)
different audience from a manual, and serves a (slightly) different
purpose, but contains (largely) similar info. Worth having both, IMO.

Re: Procedure for changing the FAQ

[Eli Zaretskii]

> From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> Date: Wed, 23 Apr 2003 09:11:10 -0400
> 
> I think the FAQ has generally not been maintained very well for the simple
> reason that such FAQs should be addressed by the manual rather than
> by a FAQ.

This is impossible in practice, from my experience: many FAQs involve
several issues described in unrelated places in the manual, or even in
different manuals, and as we all know, Richard thinks the manual is
already too large for us to add all that.

FAQs also tend to involve many minor issues that are buried in obscure
parts of the docs.

Re: Procedure for changing the FAQ

[Glenn Morris]

Thanks for the info, Eli.

"Eli Zaretskii" wrote:

>> From: Glenn Morris <gmorris+mail@ast.cam.ac.uk>
>> Date: Tue, 22 Apr 2003 16:45:07 +0100
>> 
>> ...I think the "Emacs Lisp Archive" is long dead, so I would
>> propose to delete all references to that...
[...]
> If no one disagrees, please go ahead and do this.  However, it might
> be a better idea to leave the reference to the archive and say that
> it was not updated in years.

I thought it didn't even exist anywhere on the net, but it seems the
ftp archives are still at

ftp://ftp.cis.ohio-state.edu/pub/emacs-lisp

I do think it should be downgraded to a largely historical footnote
though.

> As the Copyright line shows, Reuven Lerner does not maintain the FAQ
> actively for a few years now; we do. You will see in "cvs annotate"
> that many non-trivial changes were done by us in the FAQ over the
> last years.

Yes, I saw the CVS changes. But at the top of the current FAQ it says:

    If you have any suggestions or questions, please contact the FAQ
    maintainers <emacs-faq@lerner.co.il>.

I guess that should be changed to M-x report-emacs-bug for
suggestions, and help-gnu-emacs for questions then...


A couple more related questions for anyone who knows:

What's the best way to get changes made to
http://www.gnu.org/software/emacs/? One of the FAQ links is
out-of-date. Is mailing webmasters@www.gnu.org the best thing?

Similarly for updating the text version

http://www.gnu.org/software/emacs/emacs-faq.text

What's the best way to make plain text from Texinfo?


Should a FAQ be posted to gnu.emacs.help on a regular basis? I know a
lot of newsgroups that regularly post FAQ lists. Personally, I'm not
sure it helps much.

Re: Procedure for changing the FAQ

[Eli Zaretskii]

> From: Glenn Morris <gmorris+mail@ast.cam.ac.uk>
> Mail-Followup-To: Eli Zaretskii <eliz@elta.co.il>, emacs-devel@gnu.org
> Date: Wed, 23 Apr 2003 19:37:57 +0100
> 
> But at the top of the current FAQ it says:
> 
>     If you have any suggestions or questions, please contact the FAQ
>     maintainers <emacs-faq@lerner.co.il>.
> 
> I guess that should be changed to M-x report-emacs-bug for
> suggestions

Indeed.  It's been a long time since the FAQ started to be maintained
by the Emacs project per se, so I guess it's time to change that line.

> What's the best way to get changes made to
> http://www.gnu.org/software/emacs/? One of the FAQ links is
> out-of-date. Is mailing webmasters@www.gnu.org the best thing?

The right way is to modify that page via CVS.  gnu.org sysadmins will
need to set you up for write access to that part of the GNU CVS.

> Similarly for updating the text version
> 
> http://www.gnu.org/software/emacs/emacs-faq.text

Same answer.

> What's the best way to make plain text from Texinfo?

Use "makeinfo --no-headers --output=emacs-faq.text".

> Should a FAQ be posted to gnu.emacs.help on a regular basis? I know a
> lot of newsgroups that regularly post FAQ lists.

I think the Emacs FAQ is way too large for this.  (Reuven Lerner used
to post the FAQ regularly in several parts, but I always found that to
be annoying.)

Re: Procedure for changing the FAQ

[Simon Josefsson]

"Eli Zaretskii" <eliz@elta.co.il> writes:

>> Should a FAQ be posted to gnu.emacs.help on a regular basis? I know a
>> lot of newsgroups that regularly post FAQ lists.
>
> I think the Emacs FAQ is way too large for this.  (Reuven Lerner used
> to post the FAQ regularly in several parts, but I always found that to
> be annoying.)

One approach is to post the table of contents, with a link to the
complete FAQ, on a regular basis.

Re: Procedure for changing the FAQ

[Robert J. Chassell]

    What's the best way to make plain text from Texinfo?

I like:

    makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
    --verbose --no-headers --output=foo.txt foo.texi

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Procedure for changing the FAQ

[Richard Stallman]

    What's the best way to get changes made to
    http://www.gnu.org/software/emacs/?

I can do it.