Re: Procedure for changing the FAQ

[kai.grossjohann@gmx.net (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)