From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eshel Yaron via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Date: Sat, 07 Oct 2023 21:02:19 +0200 Message-ID: References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> Reply-To: Eshel Yaron Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4927"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 66303@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Oct 07 21:03:02 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qpCZp-0000yB-Ms for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 07 Oct 2023 21:03:01 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qpCZg-0006JK-3H; Sat, 07 Oct 2023 15:02:52 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qpCZX-0006BU-PT for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2023 15:02:44 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qpCZX-0008MI-0v for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2023 15:02:43 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qpCZq-00030L-Hi for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2023 15:03:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 07 Oct 2023 19:03:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66303 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169670536511520 (code B ref 66303); Sat, 07 Oct 2023 19:03:02 +0000 Original-Received: (at 66303) by debbugs.gnu.org; 7 Oct 2023 19:02:45 +0000 Original-Received: from localhost ([127.0.0.1]:55930 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qpCZY-0002zi-5V for submit@debbugs.gnu.org; Sat, 07 Oct 2023 15:02:45 -0400 Original-Received: from mail.eshelyaron.com ([107.175.124.16]:60890 helo=eshelyaron.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qpCZV-0002zY-CM for 66303@debbugs.gnu.org; Sat, 07 Oct 2023 15:02:43 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1696705341; bh=kc0EJTS8hJCUrfEhty0itZGUlID5aszjP7vIhOxtgHY=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=d1ZxEFCigXKgGEt+bMaHkZSMQfDejVIbFSTJp2/xws0fmqr3s6j6xeNaheufFP5IW 65vBJNW/6ARk6SKo3VTaE1q25qh5Bv76Tk8oFJfDkb24XZE9dRD9HG7SEj3QGP69j4 ESlelFVbRNZgOSlQHGRHWFufutVehdX6+Jzbi4f/QWFgj/xF+zoW7n1Jsa2YcC0cak t0bUbahfXNaM5hMNRjbhbIptf+A60UOzRuKcQFQJck/bZF0+ppWyc2NkGoU2VafLc0 e3QVnJwYMmAA7Ob8vkm3/JSfUZpoAoHT0WUUGEgJfr/pOyDS/7HwqzsMb4ltCuaxS1 zFbcx6giRy61A== In-Reply-To: <83bkda28rr.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 07 Oct 2023 10:26:16 +0300") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:272039 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Eshel Yaron >> 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: --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=v3-0001-Document-M-x-align-in-the-Emacs-manual.patch >From 92bf5e98a119d72de9f7b3b06db0d209bed33b26 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH v3] Document 'M-x align' in the Emacs manual * doc/emacs/indent.texi (Alignment): New section. * doc/emacs/emacs.texi: Update menu. --- doc/emacs/emacs.texi | 1 + doc/emacs/indent.texi | 230 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 231 insertions(+) diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index f9096557c24..da9696dfa4b 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -594,6 +594,7 @@ Top * Tab Stops:: Stop points for indentation in Text modes. * Just Spaces:: Using only space characters for indentation. * Indent Convenience:: Optional indentation features. +* Code Alignment:: Making common parts of lines start at the same column. Commands for Human Languages diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi index 17b663d22e1..4d149c903c2 100644 --- a/doc/emacs/indent.texi +++ b/doc/emacs/indent.texi @@ -55,6 +55,7 @@ Indentation * Tab Stops:: Stop points for indentation in Text modes. * Just Spaces:: Using only space characters for indentation. * Indent Convenience:: Optional indentation features. +* Code Alignment:: Making common parts of lines start at the same column. @end menu @node Indentation Commands @@ -265,3 +266,232 @@ Indent Convenience by default. To toggle this minor mode, type @kbd{M-x electric-indent-mode}. To toggle the mode in a single buffer, use @kbd{M-x electric-indent-local-mode}. + +@node Code Alignment +@section Code Alignment +@cindex code alignment +@cindex aligning code + + @dfn{Alignment} is the process of adjusting whitespace in a sequence +of lines in the region such that in all lines certain parts begin at +the same column. This is usually something you do to enhance +readability of a piece of text or code. 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 + +@noindent +is commonly aligned to: + +@example +int a = 1; +short foo = 2; +double blah = 4; +@end example + +@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. + +@vindex align-rules-list +@vindex align-mode-rules-list +The user option @code{align-rules-list} says which alignment rules +@kbd{M-x align} should consult. The value of this option is a list +with elements describing alignment rules. Each element is a cons cell +@code{(@var{title} . @var{attributes})}, where @var{title} is the name +of the alignment rule as a symbol, and @var{attributes} is a list of +rule attributes that define when the rule should apply and how it +partitions and aligns lines. Each rule attribute is a cons cell +@code{(@var{attribute} . @var{value})}, where @var{attribute} is the +name of attribute and @var{value} is its value. The only required +attribute is @code{regexp}, whose value is a regular expression with +sub-expressions matching the parts of each line where @kbd{M-x align} +should expand or contract whitespace. See the documentation string of +@code{align-rules-list} (@kbd{C-h v align-rules-list @key{RET}}) for a +full description of possible alignment rule attributes. By default, +this option is set to a long list of alignment rules for many +languages that Emacs supports. The default rules use the @code{modes} +rule attribute to specify major modes in which @kbd{M-x align} should +apply them. Major modes can also override @code{align-rules-list} by +setting the buffer-local variable @code{align-mode-rules-list} to a +non-@code{nil} list of alignment rules. When +@code{align-mode-rules-list} is non-@code{nil}, @kbd{M-x align} +consults it instead of @code{align-rules-list}. + +@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 +these exclusion rules. Similarly to @code{align-rules-list}, the +value of @code{align-exclude-rules-list} is also a list of cons cells +that describe the exclusion rules. By default, +@code{align-exclude-rules-list} includes rules that exclude alignment +in quoted strings and comments in Lisp, C and other languages. Beyond +the default exclusion rules in @code{align-exclude-rules-list}, major +modes can define bespoke exclusion rules by setting +@code{align-mode-exclude-rules-list} to a non-@code{nil} list of +rules, this overrides @code{align-exclude-rules-list} just like +@code{align-mode-rules-list} overrides @code{align-rules-list}. + +@vindex align-region-separate +@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 all matching alignment rule by expanding or contracting +stretches of whitespace. @kbd{M-x align} consistently aligns all +lines inside a single section, but it may align different sections in +the region differently. The user option @code{align-region-separate} +specifies how @kbd{M-x align} separates the region to sections. This +option can be one of the symbols @code{entire}, @code{group}, or a +regular expression. If @code{align-region-separate} is @code{entire}, +Emacs aligns the entire region as a single section. If this option is +@code{group}, Emacs aligns each group of consecutive non-blank lines +in the region as a separate section. If @code{align-region-separate} +is a regular expression, @kbd{M-x align} scans the region for matches +to that regular expression and treats them as section separators. By +default @code{align-region-separate} is set to a regular expression +that matches blank lines and lines that contains only whitespace and a +single curly brace (@samp{@{} or @samp{@}}). For special cases where +regular expressions are not accurate enough, you can also set +@code{align-region-separate} to a function that says how to separate +the region to alignment sections. See the documentation string of +@code{align-region-separate} for more details. Specific alignment +rules can override the value of @code{align-region-separate} and +define their own section separator by specifying the @code{separate} +rule attribute. + +If you call @kbd{M-x align} with a prefix argument (@kbd{C-u}), 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 + +@noindent +Typing (@kbd{C-u M-x align}) yields: + +@lisp +(set-face-attribute 'mode-line-inactive nil + :box nil + :background nil + :underline "black") +@end lisp + +In most cases, you should try @kbd{M-x align} without a prefix +argument first, and if that doesn't produce the right result you can +undo with @kbd{C-/} and try again with @kbd{C-u M-x align}. + +@findex align-highlight-rule +@findex align-unhighlight-rule +You can use the command @kbd{M-x align-highlight-rule} to visualize +the effect of a specific alignment or exclusion rule in the current +region. This command prompts you for the title of a rule and +highlights the parts on the region that this rule affects. For +alignment rules, this command highlights the whitespace that @kbd{M-x +align} would expand or contract, and for exclusion this command +highlights the parts that @kbd{M-x align} would exclude from +alignment. To remove the highlighting that this command creates, type +@kbd{M-x align-unhighlight-rule}. + +@findex align-current +@findex align-entire + The command @kbd{M-x align-current} is similar to @kbd{M-x align}, +except that it operates only on the alignment section that contains +point regardless of the current region. This command determines the +boundaries of the current section according to the section separators +that @code{align-region-separate} define. @kbd{M-x align-entire} is +another variant of @kbd{M-x align}, that disregards +@code{align-region-separate} and aligns the entire region as a single +alignment section with consistent alignment. If you set +@code{align-region-separate} to @code{entire}, @kbd{M-x align} behaves +like @kbd{M-x align-entire} by default. To illustrate the effect of +aligning the entire region as a single alignment section, consider the +following code: + +@example +one = 1; +foobarbaz = 2; + +spam = 3; +emacs = 4; +@end example + +@noindent +when the region covers all of these lines, typing @kbd{M-x align} +yields: + +@example +one = 1; +foobarbaz = 2; + +spam = 3; +emacs = 4; +@end example + +@noindent +On the other hand, @kbd{M-x align-entire} aligns all of the lines as a +single section, so the @samp{=} appears at the same column in all +lines: + +@example +one = 1; +foobarbaz = 2; + +spam = 3; +emacs = 4; +@end example + +@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 +prefix argument, it also prompts you for the sub-expression to use and +lets you specify the amount of whitespace to use as padding, as well +as whether to apply the rule repeatedly to all matches of the regular +expression in each line. + +@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}. By default +@code{align-indent-before-aligning} is set to @code{nil}. + +@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. By default, this +option is set to @code{indent-tabs-mode}, so alignment respects tab +stops in buffers that use tabs for indentation. @xref{Just Spaces}. + +@vindex align-default-spacing + The user option @code{align-default-spacing} specifies the default +amount of whitespace that @kbd{M-x align} and its related commands use +for padding between the different parts of each line when aligning it. +When @code{align-to-tab-stop} is @code{nil}, the value of +@code{align-default-spacing} is the number of spaces to use for +padding; when @code{align-to-tab-stop} is non-@code{nil}, the value of +@code{align-default-spacing} is instead the number of tab stops to +use. Each alignment rule can override the default that +@code{align-default-spacing} specifies with the @code{spacing} +attribute rule. -- 2.42.0 --=-=-=--