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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66303 in the body.
You can then email your comments to 66303 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Eshel Yaron <me <at> eshelyaron.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Document 'M-x align' in the Emacs manual
Date: Mon, 02 Oct 2023 10:21:58 +0200

[Message part 1 (text/plain, inline)]

Tags: patch

Hi,

This is a request for documenting `M-x align` in the Emacs manual, along
with a suggested draft for such documentation.


Best,

Eshel

[0001-Document-M-x-align-in-the-Emacs-manual.patch (text/patch, attachment)]

Message #8 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: Mon, 02 Oct 2023 19:05:24 +0300

> Date: Mon, 02 Oct 2023 10:21:58 +0200
> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> This is a request for documenting `M-x align` in the Emacs manual, along
> with a suggested draft for such documentation.

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?

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

From: Eshel Yaron <me <at> eshelyaron.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66303 <at> debbugs.gnu.org
Subject: Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual
Date: Mon, 02 Oct 2023 21:30:59 +0200

Hi,

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Mon, 02 Oct 2023 10:21:58 +0200
>> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>>
>> This is a request for documenting `M-x align` in the Emacs manual, along
>> with a suggested draft for such documentation.
>
> 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?

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.

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

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

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

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

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 (text/x-patch, attachment)]

Message #22 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: Sat, 07 Oct 2023 10:26:16 +0300

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

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

From: Eshel Yaron <me <at> eshelyaron.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66303 <at> debbugs.gnu.org
Subject: Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual
Date: Sat, 07 Oct 2023 21:02:19 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Eshel Yaron <me <at> eshelyaron.com>
>> Cc: 66303 <at> 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 (text/x-patch, attachment)]

Message #28 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: Sat, 14 Oct 2023 11:00:50 +0300

> From: Eshel Yaron <me <at> eshelyaron.com>
> Cc: 66303 <at> debbugs.gnu.org
> Date: Sat, 07 Oct 2023 21:02:19 +0200
> 
> New patch:

Thanks.  I have a couple of minor issues, and then we can install
this:

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

Whenever you use @dfn, you introduce new terminology.  New terminology
should always be indexed, so that readers could easily find its
description.  So for the above paragraph there should be

  @cindex alignment rules.

> +@vindex align-exclude-rules-list
> +@vindex align-mode-exclude-rules-list
> +Besides alignment rules, @kbd{M-x align} uses another kind of rules
> +called @dfn{exclusion rules}.  The exclusion rules say which parts in
> +the region @kbd{M-x align} should not align and instead leave them
> +intact.  The user option @code{align-exclude-rules-list} specifies

And here we should have

  @cindex align exclusion rules

> +@findex align-regexp
> +  The command @kbd{M-x align-regexp} lets you align the current region
> +with an alignment rule that you define ad-hoc, instead of using the
> +predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
> +prompts you for a regular expression and uses that expression as the
> +@code{regexp} attribute for an ad-hoc alignment rule that this command
> +uses to align the current region.  By default, this command adjusts
> +the whitespace that matches the first sub-expression of the regular
> +expression you specify.  If you call @kbd{M-x align-regexp} with a

Here and elsewhere you mention regexp sub-expressions.  Please add in
those places a cross-reference to where sub-expressions are described
in the manual, since this is an advanced aspect of regexps with which
some readers might not be well acquainted.

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

From: Eshel Yaron <me <at> eshelyaron.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66303 <at> debbugs.gnu.org
Subject: Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual
Date: Sat, 14 Oct 2023 12:02:20 +0200

[Message part 1 (text/plain, inline)]

Hi Eli,

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Eshel Yaron <me <at> eshelyaron.com>
>> Cc: 66303 <at> debbugs.gnu.org
>> Date: Sat, 07 Oct 2023 21:02:19 +0200
>>
>> New patch:
>
> Thanks.  I have a couple of minor issues, and then we can install
> this:
>

Great.

>> +@findex align
>> +  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.
>
> Whenever you use @dfn, you introduce new terminology.  New terminology
> should always be indexed, so that readers could easily find its
> description.  So for the above paragraph there should be
>
>   @cindex alignment rules.
>

Alright, thanks for the explanation, that makes sense.

>> +@vindex align-exclude-rules-list
>> +@vindex align-mode-exclude-rules-list
>> +Besides alignment rules, @kbd{M-x align} uses another kind of rules
>> +called @dfn{exclusion rules}.  The exclusion rules say which parts in
>> +the region @kbd{M-x align} should not align and instead leave them
>> +intact.  The user option @code{align-exclude-rules-list} specifies
>
> And here we should have
>
>   @cindex align exclusion rules
>

Done.

>> +@findex align-regexp
>> +  The command @kbd{M-x align-regexp} lets you align the current region
>> +with an alignment rule that you define ad-hoc, instead of using the
>> +predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
>> +prompts you for a regular expression and uses that expression as the
>> +@code{regexp} attribute for an ad-hoc alignment rule that this command
>> +uses to align the current region.  By default, this command adjusts
>> +the whitespace that matches the first sub-expression of the regular
>> +expression you specify.  If you call @kbd{M-x align-regexp} with a
>
> Here and elsewhere you mention regexp sub-expressions.  Please add in
> those places a cross-reference to where sub-expressions are described
> in the manual, since this is an advanced aspect of regexps with which
> some readers might not be well acquainted.

Sure, I've added cross-references to the "Regular Expressions" node in
the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
the Emacs manual, if you think that's preferable.

Here's the new patch (v4):

[v4-0001-Document-M-x-align-in-the-Emacs-manual.patch (text/x-patch, attachment)]

Message #34 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: Sat, 14 Oct 2023 13:26:04 +0300

> From: Eshel Yaron <me <at> eshelyaron.com>
> Cc: 66303 <at> debbugs.gnu.org
> Date: Sat, 14 Oct 2023 12:02:20 +0200
> 
> > Here and elsewhere you mention regexp sub-expressions.  Please add in
> > those places a cross-reference to where sub-expressions are described
> > in the manual, since this is an advanced aspect of regexps with which
> > some readers might not be well acquainted.
> 
> Sure, I've added cross-references to the "Regular Expressions" node in
> the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
> the Emacs manual, if you think that's preferable.

It is better to cross-reference to the same manual, assuming it does
document the sub-expressions.  Only if it doesn't document them well
enough should we cross-reference to ELisp.

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

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

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Eshel Yaron <me <at> eshelyaron.com>
>> Cc: 66303 <at> debbugs.gnu.org
>> Date: Sat, 14 Oct 2023 12:02:20 +0200
>>
>> > Here and elsewhere you mention regexp sub-expressions.  Please add in
>> > those places a cross-reference to where sub-expressions are described
>> > in the manual, since this is an advanced aspect of regexps with which
>> > some readers might not be well acquainted.
>>
>> Sure, I've added cross-references to the "Regular Expressions" node in
>> the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
>> the Emacs manual, if you think that's preferable.
>
> It is better to cross-reference to the same manual, assuming it does
> document the sub-expressions.  Only if it doesn't document them well
> enough should we cross-reference to ELisp.

Neither manual documents the concept of sub-expressions in detail
AFAICT, both only describe the relevant syntax.  The text in the Elisp
manual seems a bit more relevant to me, but I can see how sticking to
the Emacs manual may be preferable.  I'm attaching a revised (v5) patch
that refers to "Regexp Backslash" in the Emacs manual instead.  I've
also added a reference to this bug number in the commit message:

[v5-0001-Document-M-x-align-in-the-Emacs-manual.patch (text/x-patch, attachment)]

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

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

> From: Eshel Yaron <me <at> eshelyaron.com>
> Cc: 66303 <at> debbugs.gnu.org
> Date: Sat, 14 Oct 2023 12:47:05 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> From: Eshel Yaron <me <at> eshelyaron.com>
> >> Cc: 66303 <at> debbugs.gnu.org
> >> Date: Sat, 14 Oct 2023 12:02:20 +0200
> >>
> >> > Here and elsewhere you mention regexp sub-expressions.  Please add in
> >> > those places a cross-reference to where sub-expressions are described
> >> > in the manual, since this is an advanced aspect of regexps with which
> >> > some readers might not be well acquainted.
> >>
> >> Sure, I've added cross-references to the "Regular Expressions" node in
> >> the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
> >> the Emacs manual, if you think that's preferable.
> >
> > It is better to cross-reference to the same manual, assuming it does
> > document the sub-expressions.  Only if it doesn't document them well
> > enough should we cross-reference to ELisp.
> 
> Neither manual documents the concept of sub-expressions in detail
> AFAICT, both only describe the relevant syntax.  The text in the Elisp
> manual seems a bit more relevant to me, but I can see how sticking to
> the Emacs manual may be preferable.  I'm attaching a revised (v5) patch
> that refers to "Regexp Backslash" in the Emacs manual instead.  I've
> also added a reference to this bug number in the commit message:

Thanks, installed on the emacs-29 branch, and closing the bug.

Previous Next

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