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

Previous Next

Full log

Message #14 received at 66303 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eshel Yaron <me <at> eshelyaron.com>
Cc: 66303 <at> debbugs.gnu.org
Subject: Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual
Date: Thu, 05 Oct 2023 10:52:06 +0300

> From: Eshel Yaron <me <at> eshelyaron.com>
> Cc: 66303 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.