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: Mon, 02 Oct 2023 21:30:59 +0200
>>
>> > Thanks, but it seems to me we will be better off expanding the doc
>> > string(s) of the respective functions and variables.  The text you
>> > suggest to add documents one command and 2 user options, and provides
>> > an example of the usage.  I think adding the example to the doc string
>> > of 'align' and mentioning the two options in its doc string, as well
>> > as expanding the doc strings of those two options, would give us the
>> > same benefits without the downsides (extra *.texi file, a larger
>> > manual, etc.)
>> >
>> > WDYT?
>>
>> Thanks for taking a look.  I think that documenting `M-x align` in the
>> manual has some benefits that aren't completely covered by enhancing
>> docstrings.  Namely, you can link to the Info from other manuals, such
>> as manuals of packages that extend/integrate with `align.el`.  I also
>> think it helps with discoverability.  (For instance, you can skim the
>> manual online even without using Emacs.)
>>
>> How would you feel about a new section in indent.texi instead of a new
>> .texi file?
>
> That's better.

Alright, I'm attaching an updated patch below.

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

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


Anyhow, here's the updated patch:

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