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: 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.  But the text should be more than just mentioning a
couple of variables, or else addition to the manual is not justified.

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.