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

[Eshel Yaron]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: 66303@debbugs.gnu.org
>> Date: Thu, 05 Oct 2023 12:46:24 +0200
>>
>> 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.
>

Thanks, I'm attaching an updated patch (v3) following your comments.

>> 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.
>

So it seems.  That's fine, of course.

>> Anyhow, here's the updated patch:
>
> Thanks, some comments below.
>

Thanks.

>> +@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.
>

Alright, updated to "Code Alignment".

>> +  @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.
>

Done.

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

Updated.

>>                   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).
>

Thanks, I've added @noindent.

>> +  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.
>

Yes, I wasn't really sure about documenting `align-rules-list` here,
I've now added a description in the updated patch.

>> +@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.
>

Done.

>>                               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.
>

Sure, that makes sense.  I've added some words along these lines.

>> +@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.
>

Alright, I've elaborated about "sections", mostly in the description of
`align-region-separate`.

>>                                             @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.
>

Done.

>> +@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.
>

Alright, I've mentioned the default value in the updated patch.

>> +@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.
>

Updated with an explanation of the default value.

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

Sure, in the updated patch I've described `align-highlight-rule` and
`align-unhighlight-rule`.  I've also documented `align-regexp` and
`align-default-spacing`.

New patch:

v3-0001-Document-M-x-align-in-the-Emacs-manual.patch
Description: Text Data