bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 66303@debbugs.gnu.org
> Date: Thu, 05 Oct 2023 12:46:24 +0200
> 
> > But the text should be more than just mentioning a couple of
> > variables, or else addition to the manual is not justified.
> 
> In this v2 patch I've also described `M-x align-current`
> and `M-x align-entire`.  Are there any further details that should be
> mentioned?

I think we need more, see below.

> I think that documentation in the manual provides a more authoritative
> answer for users to the question "how do you do alignment with Emacs?"
> than the docstrings of `M-x align` and friends can, since those
> docstrings mostly concern with their respective commands and variables.

That is not the correct view, IMO.  Both the doc strings and the
manual are equally "authoritative".  It's just that the doc strings
have a narrow focus and scope, whereas the manual can easily present a
more general view.

> This can also point you to `M-x align` in the first place.  Also, as I
> mentioned above, describing this command in the manual allows other
> manuals to link to this description instead of having to describe it
> themselves.  The AUCTeX manual, for example, mentions `align-current`
> without providing a relevant reference.

That's not our problem, quite bluntly.  Let the authors of those other
manuals get their act together and provide whatever missing
information we don't provide.  They should not expect us to document
everything they need for the purposes of the use of their packages.

> > The basic question to ask yourself is: are the doc strings in align.el
> > enough to allow users to use this feature, or will they need some
> > "glue" and auxiliary explanations that provide a clearer picture?  If
> > the latter is needed, that's the stuff to put in the manual.
> 
> Basically, ISTM that this feature is important enough to be mentioned in
> the manual, regardless of the clarity of the docstrings in align.el.

That's not what I said, and not how we consider the issue of
documenting features in the manual.  Once again, the doc strings and
the apropos commands are an integral part of the Emacs documentation
system, so not every important command or function or variable must be
in the manuals.

> Many commands in Emacs have perfectly clear docstrings that give you the
> full picture, but that doesn't preclude them from being documented in
> the manual.  I don't find that redundant because I think the manual
> serves a somewhat different purpose (with some different upsides that I
> mentioned above).  Does that make sense?

Your views are different from the project's views in this matter.  We
look at this differently.

> Anyhow, here's the updated patch:

Thanks, some comments below.

> +@node Alignment
> +@section Alignment
> +@cindex alignment

The section and the index entry, and possibly also the node, should be
"Code Alignment" or maybe "Source Code Alignment", not just
"Alignment", which is too general/generic.

> +  @dfn{Alignment} is the process of adjusting whitespace in a sequence
> +of lines such that in all lines certain parts begin at the same
> +column.

I think this should say "lines in the region", rather than just
"series of lines", since the commands work on the region.

>          This is usually done to enhance readability of a piece of
> +text or code.

Passive tense alert!

>                   The classic example is aligning a series of assignments
> +in C-like programming languages:
> +
> +@example
> +int a = 1;
> +short foo = 2;
> +double blah = 4;
> +@end example
> +
> +Is commonly aligned to:

You want @outdent before the last line, and maybe also start it from a
non-capital letter (as it is a continuation of the previous sentence).

> +  You can use the command @kbd{M-x align} to align lines in the
> +current region.  This command knows about common alignment patterns
> +across many markup and programming languages.  It encodes these
> +patterns as a set of @dfn{alignment rules}, that say how to align
> +different kinds of text in different contexts.

Saying this without documenting align-rules-list makes the manual much
less useful, IMO.

> +@kbd{M-x align} splits the region into a series of @dfn{sections},
> +usually sequences of non-blank lines, and aligns each section
> +according to a matching alignment rule by expanding or contracting
> +stretches of whitespace.

And here, I would at least mention align-region-separate.

>                               If you call this command with a prefix
> +argument (@kbd{C-u M-x align}), it enables more alignment rules that
> +are often useful but may sometimes be too intrusive.  For example, in
> +a Lisp buffer with the following form:
> +
> +@lisp
> +(set-face-attribute 'mode-line-inactive nil
> +                    :box nil
> +                    :background nil
> +                    :underline "black")
> +@end lisp
> +
> +Typing (@kbd{C-u M-x align}) yields:
> +
> +@lisp
> +(set-face-attribute 'mode-line-inactive nil
> +                    :box                nil
> +                    :background         nil
> +                    :underline          "black")
> +@end lisp

This should probably be followed by advice to try "M-x align" first,
and if that doesn't produce the desirable result, follow up with C-/
and "C-u M-x align", right?  Otherwise the above text looks incomplete
to me.

> +@findex align-current
> +@findex align-entire
> +  The command @kbd{M-x align-current} is similar to to @kbd{M-x
> +align}, except that it operates only on the section that contains
> +point, regardless of the current region.

This should define "section", and tell something about how to identify
where the point's section begins and ends.  Probably related to the
description of align-region-separate above.

>                                             @kbd{M-x align-entire} is
> +another variant of @kbd{M-x align}, that aligns the entire region as a
> +single alignment section with consistent alignment, disregarding blank
> +lines and similar hints that @kbd{M-x align} uses to separate the
> +region into multiple alignment sections.

An example of how the results are different is in order here, I think.

> +@vindex align-indent-before-aligning
> +  If the user option @code{align-indent-before-aligning} is
> +non-@code{nil}, Emacs indents the region before aligning it with
> +@kbd{M-x align}.  @xref{Indentation}.

We usually document in the manual the default value of each option.

> +@vindex align-to-tab-stop
> +  The user option @code{align-to-tab-stop} says whether aligned parts
> +should start at a tab stop (@pxref{Tab Stops}).  If this option is
> +@code{nil}, @kbd{M-x align} uses just enough whitespace for alignment,
> +disregarding tab stops.  If this is a non-@code{nil} symbol, @kbd{M-x
> +align} checks the value of that symbol, and if this value is
> +non-@code{nil}, @kbd{M-x align} aligns to tab stops.

This is incomplete without describing the default value of the option.

Should we also document align-highlight-rule, together with when it is
useful?

Thanks.