From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 02 Oct 2023 08:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 66303 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: 66303@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.169623495211769 (code B ref -1); Mon, 02 Oct 2023 08:23:02 +0000 Received: (at submit) by debbugs.gnu.org; 2 Oct 2023 08:22:32 +0000 Received: from localhost ([127.0.0.1]:35941 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnECG-00033k-1n for submit@debbugs.gnu.org; Mon, 02 Oct 2023 04:22:32 -0400 Received: from lists.gnu.org ([2001:470:142::17]:33352) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnECE-00033W-Ib for submit@debbugs.gnu.org; Mon, 02 Oct 2023 04:22:31 -0400 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 1qnEBr-0001We-2q for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:07 -0400 Received: from mail.eshelyaron.com ([107.175.124.16] helo=eshelyaron.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qnEBl-0005Sq-PG for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:06 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1696234920; bh=ZiIwSRrmqebEVpc0lMtff52kOKAOrYSFA9vUm+mtIgI=; h=From:To:Subject:Date:From; b=kOMDGHWjySf58bxUyD2FaU+yWPimWXqBr76VdZyEmOQWOWXVDAPl5EYecuXqPQjZP 7xeN5Vsd1plnNyxbmaCcYLjtxQ4YA9Jg9NXv4jv/DCNpV0cAi9BfPb/fzUnjDtj8CY nrHD6Jga+BY30LY+U88dWvIOVCRAZ0l6FgdljnBycYEG6zxss52bRgdUBN0t/DF9gW 2qa6YCiMwmCZ4iBoQOmFMDqynmjqSyifoPxTQFkqCRfR/o3OD2pUC2M6ilJYtwwUcD LBboalRJ7iw97d1G+Ft28znWMUqYsN3m1Dqmc0wPLanQSYdAb2W0nntBw+pEJWboK4 npR4OgvyatIYA== From: Eshel Yaron X-Hashcash: 1:20:231002:bug-gnu-emacs@gnu.org::09bnJvPqIqQRObOp:Nu/ Date: Mon, 02 Oct 2023 10:21:58 +0200 Message-ID: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=107.175.124.16; envelope-from=me@eshelyaron.com; helo=eshelyaron.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FORGED_SPF_HELO=0.799, SPF_HELO_PASS=-0.001, T_SPF_TEMPERROR=0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain 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 --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Document-M-x-align-in-the-Emacs-manual.patch >From 20fa3ea348617350fa8a437fad75aa9e9a9a620f Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH] Document 'M-x align' in the Emacs manual * doc/emacs/align.texi: New file. * doc/emacs/emacs.texi: Include it and update menu. --- doc/emacs/align.texi | 70 ++++++++++++++++++++++++++++++++++++++++++++ doc/emacs/emacs.texi | 2 ++ 2 files changed, 72 insertions(+) create mode 100644 doc/emacs/align.texi diff --git a/doc/emacs/align.texi b/doc/emacs/align.texi new file mode 100644 index 00000000000..c7e48890695 --- /dev/null +++ b/doc/emacs/align.texi @@ -0,0 +1,70 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2023 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Alignment +@chapter Alignment +@cindex 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. This is usually done 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 + +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. + +@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. 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 + +@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}. + +@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. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 7a21eb49e24..c4ed9a6ae93 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -178,6 +178,7 @@ Top Advanced Features * Modes:: Major and minor modes alter Emacs's basic behavior. * Indentation:: Editing the white space at the beginnings of lines. +* Alignment:: Making common parts of lines start at the same column. * Text:: Commands and modes for editing human languages. * Programs:: Commands and modes for editing programs. * Building:: Compiling, running and debugging programs. @@ -1616,6 +1617,7 @@ Intro @include mule.texi @include modes.texi @include indent.texi +@include align.texi @include text.texi @c Includes fortran-xtra. @include programs.texi -- 2.42.0 --=-=-=-- From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 02 Oct 2023 16:06: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 To: Eshel Yaron Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169626275128599 (code B ref 66303); Mon, 02 Oct 2023 16:06:02 +0000 Received: (at 66303) by debbugs.gnu.org; 2 Oct 2023 16:05:51 +0000 Received: from localhost ([127.0.0.1]:37791 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnLQc-0007RC-R5 for submit@debbugs.gnu.org; Mon, 02 Oct 2023 12:05:51 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47676) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnLQb-0007Qt-Dk for 66303@debbugs.gnu.org; Mon, 02 Oct 2023 12:05:49 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qnLQF-0008N1-3z; Mon, 02 Oct 2023 12:05:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=f7P+XlcbQOUxDVAebE7S9sd07t0EDvJBc3db6paQIB4=; b=mVz6jcWwyU7J 1eNmX5HJ0EQG6EpKnc8Qu64n4v5dADsVE6ZGJsTPUGWPsCXuF3Sk+xLZMjo+Y6D0FFqyT3Jb+1OOb bNWZvkkVjOMhDMhj/mm54KU/ZjesfwFOr789WSEGVgjD5ezcucjogjiNCXgYd/14xAkPLJ3ZvIBNF E4Sa/HBCTv52VB+EWpkTCMNrGjet3jt4x+4P/C2NmEeP2F01ayqywQvIoljTQiuYQ0+24HYbCLeUK hVyOQFGY72wosZ+LB4J2sOwSeaXnSs0GAJbHl1kNMN/XCH+zz1tnu7eQGMKTIS7vdwrudsW86NCgv /BPbUsZ9H3Bm4SJGmNIYrA==; Date: Mon, 02 Oct 2023 19:05:24 +0300 Message-Id: <83wmw56md7.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (bug-gnu-emacs@gnu.org) References: X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > 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" > > 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? From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 02 Oct 2023 19:32: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 To: Eli Zaretskii Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169627509518453 (code B ref 66303); Mon, 02 Oct 2023 19:32:02 +0000 Received: (at 66303) by debbugs.gnu.org; 2 Oct 2023 19:31:35 +0000 Received: from localhost ([127.0.0.1]:38094 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnOdi-0004nY-V0 for submit@debbugs.gnu.org; Mon, 02 Oct 2023 15:31:35 -0400 Received: from mail.eshelyaron.com ([107.175.124.16]:51270 helo=eshelyaron.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnOdS-0004n3-IO for 66303@debbugs.gnu.org; Mon, 02 Oct 2023 15:31:33 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1696275061; bh=RbXBIH3FKNInJxpejZkbbtWQOqYYxGbRY23tGZNIbL0=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=T+DJfxUNq1/raTOn3WAh4ElI5VtvOdKfWZfDzcY8B0rPlQHlI6sKtyKRSShpJrUSu tVqk0V/zzkcyTDOPEeMehuD8qSYC+bQZNIh4vXTTRSkCA7R6QS9HOCmschjXHNmglg h41H736GXONhXnOtPR23h75EzLT9NbvSqf6bpmllxra+LXRUrUL47siw8Zh2vMVF7V jjD0gW0P9V9CkWaTmrDA+O5N2/kEXbtW4pmKvr6UQEwKhrXhtsJjRXIr10wjVDYaiy 6WNarj52mYY0NvinIT6Rlxwga4AlEfbgLmmWfF+fh15J3HXrlH9bg7avYKuGLxgnGY 37LMmSGpFHcCQ== From: Eshel Yaron In-Reply-To: <83wmw56md7.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 02 Oct 2023 19:05:24 +0300") References: <83wmw56md7.fsf@gnu.org> X-Hashcash: 1:20:231002:66303@debbugs.gnu.org::ARTSn7Xz2/VV13Vo:1bdy X-Hashcash: 1:20:231002:eliz@gnu.org::QlOl1nLksF3vmQ9i:7ClX Date: Mon, 02 Oct 2023 21:30:59 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi, Eli Zaretskii 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" >> >> 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? From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 05 Oct 2023 07:53: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 To: Eshel Yaron Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169649234622706 (code B ref 66303); Thu, 05 Oct 2023 07:53:02 +0000 Received: (at 66303) by debbugs.gnu.org; 5 Oct 2023 07:52:26 +0000 Received: from localhost ([127.0.0.1]:45956 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qoJ9m-0005u9-Bx for submit@debbugs.gnu.org; Thu, 05 Oct 2023 03:52:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:33142) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qoJ9j-0005tv-EZ for 66303@debbugs.gnu.org; Thu, 05 Oct 2023 03:52:24 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qoJ9L-00061T-W2; Thu, 05 Oct 2023 03:52:00 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=JAh5E5mnWQ5MhTlnaNDH7kslZgfoQrlyAXojTBssg3E=; b=LfRtZvZFTgAv H6W/r3ynp7XduTt6Rg1kUw1afKGCP2B+sL68wZV0T4PNTlglyXMCDthkl8D3jHlyJSKW7Gyd18941 TH1GAjV+TQ+v+wW0ruGk7GNnDdGpFaipilJGihZPpz7prXVV54x6440y0hPbbzu+5xMnIf7jp/PUq 5cMHw9EutaeSqkn+r35mqMQEU6M3Pt2QWubI9k9WdsVq5T7Z7Xo6BfVAO8plMiYVPN26AZXog+zLV ngh/m/QIOV73+3Jf/cOBOr9lrEVHRw0d/IbJyCjIKZr8+Y+BKnqa187zJfoCOUsTj+Kd3h5FeB7d7 qhezwr+sc9Q8LzRQvcvx3g==; Date: Thu, 05 Oct 2023 10:52:06 +0300 Message-Id: <83edi94ic9.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Eshel Yaron on Mon, 02 Oct 2023 21:30:59 +0200) References: <83wmw56md7.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eshel Yaron > 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. From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 05 Oct 2023 10:47:01 +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 To: Eli Zaretskii Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.16965028149006 (code B ref 66303); Thu, 05 Oct 2023 10:47:01 +0000 Received: (at 66303) by debbugs.gnu.org; 5 Oct 2023 10:46:54 +0000 Received: from localhost ([127.0.0.1]:46108 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qoLsb-0002LB-Kv for submit@debbugs.gnu.org; Thu, 05 Oct 2023 06:46:54 -0400 Received: from mail.eshelyaron.com ([107.175.124.16]:41952 helo=eshelyaron.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qoLsT-0002Ky-4t for 66303@debbugs.gnu.org; Thu, 05 Oct 2023 06:46:52 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1696502786; bh=/iy5C5b7dym+QtPxNqWvH3IlDYw4nxMEdBMEzLzMG5Y=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=ICjW38hIxfJvJouU+Q9WSs9GwVfelhMUFs5r4UpVI2AmaWYHXFWpaI7bnHcr8YVSP MM4Ma8jeBIO1+5DaiHp9NKZnY6xEGpGotQGFUtQr6q5wOSDfjU8hcbIVKP/aVlShnU AvVyoWch2gpLLpmFNBAj1Uh+o+UVroueN0BFPqKSVBg8Cjc+FMR5mp2knjdeT/SA67 sIxZ/VhZcNBl7T7hJo44qJrjFV3eVe3VrgL79Z2t6s3N9c/hVXZ9k8DaXdsQlQAc7O ZdFd9zq6t/59j8BbTPyWuaccD7yGZBkpSYSxOBUVWI08K6XEfBYnDHaMXDYqYnHtqL WCDw23ZVH5lHA== From: Eshel Yaron In-Reply-To: <83edi94ic9.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 05 Oct 2023 10:52:06 +0300") References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> Date: Thu, 05 Oct 2023 12:46:24 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Eshel Yaron >> 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: --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=v2-0001-Document-M-x-align-in-the-Emacs-manual.patch >From 377b14cadd6a32d10662b65d0c0c20d4ef131d31 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH v2] 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 | 79 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 7a21eb49e24..3f122107392 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -595,6 +595,7 @@ Top * Tab Stops:: Stop points for indentation in Text modes. * Just Spaces:: Using only space characters for indentation. * Indent Convenience:: Optional indentation features. +* 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..e6d0246720f 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. +* Alignment:: Making common parts of lines start at the same column. @end menu @node Indentation Commands @@ -265,3 +266,81 @@ 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 Alignment +@section Alignment +@cindex 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. This is usually done 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 + +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. + +@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. 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 + +@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. @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. + +@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}. + +@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. -- 2.42.0 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Thu Oct 05 17:55:08 2023 Received: (at control) by debbugs.gnu.org; 5 Oct 2023 21:55:08 +0000 Received: from localhost ([127.0.0.1]:48856 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qoWJH-0003H0-SA for submit@debbugs.gnu.org; Thu, 05 Oct 2023 17:55:08 -0400 Received: from mail-lf1-x133.google.com ([2a00:1450:4864:20::133]:52517) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qoWJG-0003FS-K8 for control@debbugs.gnu.org; Thu, 05 Oct 2023 17:55:07 -0400 Received: by mail-lf1-x133.google.com with SMTP id 2adb3069b0e04-5042bfb4fe9so1872907e87.1 for ; Thu, 05 Oct 2023 14:54:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696542882; x=1697147682; darn=debbugs.gnu.org; h=to:subject:message-id:date:mime-version:from:from:to:cc:subject :date:message-id:reply-to; bh=pL9C+djlbFp5/Nc9ZfHVWssOMYMC21e45hMajMw6Ao0=; b=LEAS7q9Zuip3yj2UZZIa9FVPoP+/D568yFPH7LEAXfluypniDmUgGQYrm7pILCjxT6 kQ/3GTFwZOQcV52A9RUClAsoeUHqsSqTt8lPNdW9LBl3m3dU2ERbdjfTfKDeeCC006U1 D3T/EaLD9q87tbI2GhqoETUk2TIR7i1cgW6tFAqrbo/uT1uF4rJU19CeH5g80Jfw78T8 jN/eYvuQ4CtJ1hPbmQQOpDZS1h/p3CTN58ehLU69K8l/iuN6hFW/lK1fDLo+JyBvUIRa OpF3ULIUaxnK45ZW/FEylgqROzFOrdmlTWLD2DECdanyOA1MV/7vD0R9B1YYfmcUej7S rfIw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696542882; x=1697147682; h=to:subject:message-id:date:mime-version:from:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=pL9C+djlbFp5/Nc9ZfHVWssOMYMC21e45hMajMw6Ao0=; b=jh9CeUUj+E652ExDyl9YaVhv75Z4ue6bSR4g+9PP6q95LIbWMLohsGfJawT7XoRcgR hDljIdetgB1kskrrxscU84gZXPGBt2wIN3U8V6FplhlGfv0bOm9heN8QR4DuFVEgyTo7 1IsjwXDfQ+TPI/4JqfKHB7lcEGng6jrj8IM4TbhcC0BgwvckvQBCS7ylG3UiopqwmLqs I47Ib2h/W0SpmR5DybWCwNGB3vJ0qL8CHrY+tNmsirljSOSserpKA5HvELBENDdo+32p hdASOet06yghOn0DBOTmVBl3jwt7ZqW0MQw2Q7aYaj5miEZNdIL3GZiDR3fp//0mTp1U HN8A== X-Gm-Message-State: AOJu0YzBr/EcIOu+kibyyhjtnfl9wp4jVwAS9EPMreyCwv4fk0KaovrB +5giex1VP9/S7P0QiMKg87wbt13iVP2Ir1kfPX+tZZGo X-Google-Smtp-Source: AGHT+IH62fsf+6oUDzhPtsyTf6v3DNwaLt3V32J+CTvKHHhe8X3pRh9K6MkC8GM3/WhkznPulltDbJp4tWOt4EHrRIM= X-Received: by 2002:a19:2d56:0:b0:505:8075:7c17 with SMTP id t22-20020a192d56000000b0050580757c17mr5127698lft.22.1696542882035; Thu, 05 Oct 2023 14:54:42 -0700 (PDT) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Thu, 5 Oct 2023 21:54:41 +0000 From: Stefan Kangas MIME-Version: 1.0 Date: Thu, 5 Oct 2023 21:54:41 +0000 Message-ID: Subject: control message for bug #66303 To: control@debbugs.gnu.org Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) severity 66303 wishlist quit From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 07 Oct 2023 07:27:01 +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 To: Eshel Yaron Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169666359811528 (code B ref 66303); Sat, 07 Oct 2023 07:27:01 +0000 Received: (at 66303) by debbugs.gnu.org; 7 Oct 2023 07:26:38 +0000 Received: from localhost ([127.0.0.1]:53253 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qp1hu-0002zr-0X for submit@debbugs.gnu.org; Sat, 07 Oct 2023 03:26:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:41914) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qp1hr-0002za-46 for 66303@debbugs.gnu.org; Sat, 07 Oct 2023 03:26:35 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qp1hR-0004ho-QN; Sat, 07 Oct 2023 03:26:09 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=1S5ZBd5yQTZGOZ9ZAGlUoN2IG2f9v6ckYCmzn8vSj7c=; b=OcfIZsLzOZem Ki/noJGs1BW+2EyTABFKZS2lK3hLJ636T29ONkal1g2tmw4Rh8/DLKgUVsFwIcJdrWpPj9g/dTqx9 ro2KuiD6YwatcwgI/lEL7koBE5n+GFyWV0WtByoAto6opnuFgWOhDjW/2Og/9l06SPba56Ex0exsB 4QGlJz/snha1pU2K4wy7VBTS/G/3TEdcDf8UM8xmJKB3rCOehKnsz+eUQ8e+QAXs2AT9SUHT9tWis +1ueorWSEdlsgkKCMMjenKBiZUDp7O2Att2NBbfddDDmYZXhvhbl2lLvXBRebIrmAhWBIzj/tIOth +M3Otaq0SNYnFkmj0lb6BQ==; Date: Sat, 07 Oct 2023 10:26:16 +0300 Message-Id: <83bkda28rr.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Eshel Yaron on Thu, 05 Oct 2023 12:46:24 +0200) References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eshel Yaron > Cc: 66303@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. From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual 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 To: Eli Zaretskii Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169670536511520 (code B ref 66303); Sat, 07 Oct 2023 19:03:02 +0000 Received: (at 66303) by debbugs.gnu.org; 7 Oct 2023 19:02:45 +0000 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 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== From: Eshel Yaron In-Reply-To: <83bkda28rr.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 07 Oct 2023 10:26:16 +0300") References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> Date: Sat, 07 Oct 2023 21:02:19 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= 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 --=-=-=-- From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 14 Oct 2023 08:02: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 To: Eshel Yaron Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169727048524090 (code B ref 66303); Sat, 14 Oct 2023 08:02:02 +0000 Received: (at 66303) by debbugs.gnu.org; 14 Oct 2023 08:01:25 +0000 Received: from localhost ([127.0.0.1]:47800 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrZaO-0006GR-K8 for submit@debbugs.gnu.org; Sat, 14 Oct 2023 04:01:25 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53474) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrZaL-0006GC-Sn for 66303@debbugs.gnu.org; Sat, 14 Oct 2023 04:01:23 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qrZZs-0000Gd-QF; Sat, 14 Oct 2023 04:00:52 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=j3L87aEKxrWbaGj97s3y8QMl1tmdufsKwYmG2IVaNHo=; b=J+9T43X0dpe7 ET+xNN40CJWFSCkgpGZEnflcn+bdXFCSZT1cLzRdgiJYGbN3jdsrLkMFBSckJWBd50d9J5aB0RAm+ BXF4Nr5nGAMVLg4VB84+tykB3u3ZEkKVv8kmPSwKp1x4iAuEZ7LtS2A5rq6q8EDsWrE9eGRTO+vjz XjGZCJGVlDCM2dRpe4SjKMMne0Le8Fyp/rC+bKf8q6Rb0GuQM9tSYySTlg89utJXZ7kg0a3ED7JSx RlUbB/BOI6FHTJBUpEIVBe8s7oUqOKACRhDMFAYluaidynI+FaJ2TWnKW+1vEADtu/JPmizXz6og3 rIT0X2DE8DJPYxG5YeBHoQ==; Date: Sat, 14 Oct 2023 11:00:50 +0300 Message-Id: <83fs2dskel.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Eshel Yaron on Sat, 07 Oct 2023 21:02:19 +0200) References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eshel Yaron > Cc: 66303@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. From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 14 Oct 2023 10:03:01 +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 To: Eli Zaretskii Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.16972777708202 (code B ref 66303); Sat, 14 Oct 2023 10:03:01 +0000 Received: (at 66303) by debbugs.gnu.org; 14 Oct 2023 10:02:50 +0000 Received: from localhost ([127.0.0.1]:47938 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrbTt-00028C-QU for submit@debbugs.gnu.org; Sat, 14 Oct 2023 06:02:50 -0400 Received: from mail.eshelyaron.com ([107.175.124.16]:48046 helo=eshelyaron.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrbTr-000283-02 for 66303@debbugs.gnu.org; Sat, 14 Oct 2023 06:02:48 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1697277742; bh=sAyfJkgpK6SXuWJLb/RJswDXxSXroFn3HW6TOttvksE=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=ZNf2GL3v9KEAZDcCv4AOkaN2tJX//B999PhwM9rSPnVIZXttR0vL0bt+9/rxpk8Nn v0rXz5QJnfiCW9sKI14Jm3n2OhcWg6IliEtLBnNhTXKRD8nfQmgYsM8ZDe6CEiFYpE FhGuvY5yO3cyYXiojYFpKYmuZSwM5MS1D7d6+9n7OeBAjN2pT08C47o1DguM5Oo1pU yOFAQbuOJgbXGM8bBOp97gR+kXA/BUaHalSlKiZz4OqmtQ+coaqVzdUtdoJQ2Wg7TU WoWJXGI9zIAhVcZB6pAwckZK1t9KlzmvXNa8ZMZPKm8uMdB4oqebuGk1psZIoOCgHI IOkvR7f5fDzKw== From: Eshel Yaron In-Reply-To: <83fs2dskel.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 14 Oct 2023 11:00:50 +0300") References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> <83fs2dskel.fsf@gnu.org> Date: Sat, 14 Oct 2023 12:02:20 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain Hi Eli, Eli Zaretskii writes: >> From: Eshel Yaron >> Cc: 66303@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): --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=v4-0001-Document-M-x-align-in-the-Emacs-manual.patch >From 42de6a2816dc629198ede4b622eb47c6748437bf Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH v4] 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 | 236 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 237 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..a3ac5676829 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,238 @@ 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 + +@cindex alignment rules +@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 +(@pxref{Regular Expressions,,,elisp,The Emacs Lisp Reference Manual}) +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}. + +@cindex align exclusion 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 +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}. + +@cindex alignment sections +@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. @xref{Regular Expressions,,,elisp,The Emacs +Lisp Reference Manual}, for more information about regular expressions +and their sub-expressions. + +@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 --=-=-=-- From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 14 Oct 2023 10:27: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 To: Eshel Yaron Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169727919811703 (code B ref 66303); Sat, 14 Oct 2023 10:27:02 +0000 Received: (at 66303) by debbugs.gnu.org; 14 Oct 2023 10:26:38 +0000 Received: from localhost ([127.0.0.1]:47953 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrbqw-00032h-3O for submit@debbugs.gnu.org; Sat, 14 Oct 2023 06:26:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:38186) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrbqt-00032T-G5 for 66303@debbugs.gnu.org; Sat, 14 Oct 2023 06:26:36 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qrbqP-0000WW-9H; Sat, 14 Oct 2023 06:26:06 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=E+zZY0+GXzd+By5mO1S69qNk6DcOmNqwhXZMy9dSLBY=; b=cqbFnf/uXxVi 61GwL81rKPiZ08upu8u6xiQ2bGi3S8yPuVz633C6jK7rTTF66DkRZvYmO7Ym+k2AJi15E/R234Si2 YR5KKOCBgXOlkY/uuoJg/V3Mb7dDCyjW32kMdaBDTkSFckI0WyUjZIVj7svnX1DzgLEIakJlwPhNO nrdzSH7XXmUjAudnJxg0JbKX/fD8S3khRT6YJyG8HEshg7RaUHsNDeWNfsbadt9zDQsMj3OCEQkSf z3tq6LdDdU/RoPW2RttYcaz8QsBNzlaLmtuRHc2hz+M6Jdc5wdwmLiU5d0UypgtxdSTrxKYMC1kIO p+ITStCVTiq83FILn8hkPA==; Date: Sat, 14 Oct 2023 13:26:04 +0300 Message-Id: <831qdxsdoj.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Eshel Yaron on Sat, 14 Oct 2023 12:02:20 +0200) References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> <83fs2dskel.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eshel Yaron > Cc: 66303@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. From unknown Mon Jun 23 23:55:23 2025 X-Loop: help-debbugs@gnu.org Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 14 Oct 2023 10:48: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 To: Eli Zaretskii Cc: 66303@debbugs.gnu.org Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169728045724376 (code B ref 66303); Sat, 14 Oct 2023 10:48:02 +0000 Received: (at 66303) by debbugs.gnu.org; 14 Oct 2023 10:47:37 +0000 Received: from localhost ([127.0.0.1]:47977 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrcBE-0006L5-5p for submit@debbugs.gnu.org; Sat, 14 Oct 2023 06:47:37 -0400 Received: from mail.eshelyaron.com ([107.175.124.16]:55430 helo=eshelyaron.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrcB9-0006Kv-RZ for 66303@debbugs.gnu.org; Sat, 14 Oct 2023 06:47:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1697280427; bh=mniQb4p0wl0Tt3COK+WeN9VwPjgx3fPUYA0wvWBM3Ic=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=VNVKOsnrm0EAGSbxSG0nkh3rJVwRZUg5Dd3ffl+2KHuISSv2YYKPGtXYF31+LVbBA AB4CfjdaKaTXlQP+CjC7X5c9f7UiTlPz86V/aG1H3h1kZW3O6LtUUU0Eh56CicI5dW WWeO1esTKIYiMZs3O7thtiRSibc5PmDYBtRbStOkE058JKoUVhMd1qz8VhRFypAlGb fLgovxk3MTKg/9y/Bm9ZDCdTVSzIhtt2jCR39bWGTXENh/tVQoYdS0KqZAvDZLOCYF PlUr18IYNY4t7Gn8EtmZhLOSRMNgR49VuhGv55jIIxV1B3m6mEzWwu8I6KhWqciiN3 7bmkcAEJTmu9g== From: Eshel Yaron In-Reply-To: <831qdxsdoj.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 14 Oct 2023 13:26:04 +0300") References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> <83fs2dskel.fsf@gnu.org> <831qdxsdoj.fsf@gnu.org> Date: Sat, 14 Oct 2023 12:47:05 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Eshel Yaron >> Cc: 66303@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: --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=v5-0001-Document-M-x-align-in-the-Emacs-manual.patch >From 2f3b8b9651ea1629ef775cb6700bce24cc577b24 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH v5] Document 'M-x align' in the Emacs manual * doc/emacs/indent.texi (Alignment): New section. * doc/emacs/emacs.texi: Update menu. (Bug#66303) --- doc/emacs/emacs.texi | 1 + doc/emacs/indent.texi | 234 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 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..0df973c1dd0 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,236 @@ 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 + +@cindex alignment rules +@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 (@pxref{Regexp Backslash}). 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}. + +@cindex align exclusion 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 +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}. + +@cindex alignment sections +@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. @xref{Regexp Backslash}, for more +information about regular expressions and their sub-expressions. + +@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 --=-=-=-- From unknown Mon Jun 23 23:55:23 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Eshel Yaron Subject: bug#66303: closed (Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual) Message-ID: References: <83v8b9qwqx.fsf@gnu.org> X-Gnu-PR-Message: they-closed 66303 X-Gnu-PR-Package: emacs X-Gnu-PR-Keywords: patch Reply-To: 66303@debbugs.gnu.org Date: Sat, 14 Oct 2023 11:18:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1697282282-28201-1" This is a multi-part message in MIME format... ------------=_1697282282-28201-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #66303: [PATCH] Document 'M-x align' in the Emacs manual which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 66303@debbugs.gnu.org. --=20 66303: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D66303 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1697282282-28201-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 66303-done) by debbugs.gnu.org; 14 Oct 2023 11:17:44 +0000 Received: from localhost ([127.0.0.1]:47996 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrceO-0007KJ-6S for submit@debbugs.gnu.org; Sat, 14 Oct 2023 07:17:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59438) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qrceK-0007K4-6t for 66303-done@debbugs.gnu.org; Sat, 14 Oct 2023 07:17:43 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qrcdq-0001zq-Vm; Sat, 14 Oct 2023 07:17:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=+JHXJYxt+Ptafdnl4Zqlf4a1fBGABqEqXH0UuOfWK9Y=; b=R4kkfE2XQ40u /3x5gJyBZyYQGDNr2YEjZX8sCsygbI/+hFQEL1iZtHNim+ESyPJt3b9hOZykofSYXbs8tX8AjqFEh yrxmd3lk+rofaGTyLixYvmZng5M8sPqkYQyoSdVneYMYjmj+i3YZKFeDKsoFwKi7Ccw37tqtqMBFz JjpQSazVz8/hNL6YAe0I/v5zkr0cGLpcgujh08v7dhURUcVflZzWs/Bb41TeoTLLVwInGmwJo7w9o pMbvVVovk2LBZ5EjekdOPYg7Borwy77j/lvcG2ioG3fTPcbPB2BJVqPefbUjSV9BURk2tY7E31aAT vPGFmTQ0LVSYEDQtNCrR2Q==; Date: Sat, 14 Oct 2023 14:17:10 +0300 Message-Id: <83v8b9qwqx.fsf@gnu.org> From: Eli Zaretskii To: Eshel Yaron In-Reply-To: (message from Eshel Yaron on Sat, 14 Oct 2023 12:47:05 +0200) Subject: Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> <83bkda28rr.fsf@gnu.org> <83fs2dskel.fsf@gnu.org> <831qdxsdoj.fsf@gnu.org> X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 66303-done Cc: 66303-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eshel Yaron > Cc: 66303@debbugs.gnu.org > Date: Sat, 14 Oct 2023 12:47:05 +0200 > > Eli Zaretskii writes: > > >> From: Eshel Yaron > >> Cc: 66303@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. ------------=_1697282282-28201-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 2 Oct 2023 08:22:32 +0000 Received: from localhost ([127.0.0.1]:35941 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnECG-00033k-1n for submit@debbugs.gnu.org; Mon, 02 Oct 2023 04:22:32 -0400 Received: from lists.gnu.org ([2001:470:142::17]:33352) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnECE-00033W-Ib for submit@debbugs.gnu.org; Mon, 02 Oct 2023 04:22:31 -0400 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 1qnEBr-0001We-2q for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:07 -0400 Received: from mail.eshelyaron.com ([107.175.124.16] helo=eshelyaron.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qnEBl-0005Sq-PG for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:06 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1696234920; bh=ZiIwSRrmqebEVpc0lMtff52kOKAOrYSFA9vUm+mtIgI=; h=From:To:Subject:Date:From; b=kOMDGHWjySf58bxUyD2FaU+yWPimWXqBr76VdZyEmOQWOWXVDAPl5EYecuXqPQjZP 7xeN5Vsd1plnNyxbmaCcYLjtxQ4YA9Jg9NXv4jv/DCNpV0cAi9BfPb/fzUnjDtj8CY nrHD6Jga+BY30LY+U88dWvIOVCRAZ0l6FgdljnBycYEG6zxss52bRgdUBN0t/DF9gW 2qa6YCiMwmCZ4iBoQOmFMDqynmjqSyifoPxTQFkqCRfR/o3OD2pUC2M6ilJYtwwUcD LBboalRJ7iw97d1G+Ft28znWMUqYsN3m1Dqmc0wPLanQSYdAb2W0nntBw+pEJWboK4 npR4OgvyatIYA== From: Eshel Yaron To: bug-gnu-emacs@gnu.org Subject: [PATCH] Document 'M-x align' in the Emacs manual X-Hashcash: 1:20:231002:bug-gnu-emacs@gnu.org::09bnJvPqIqQRObOp:Nu/ Date: Mon, 02 Oct 2023 10:21:58 +0200 Message-ID: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=107.175.124.16; envelope-from=me@eshelyaron.com; helo=eshelyaron.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FORGED_SPF_HELO=0.799, SPF_HELO_PASS=-0.001, T_SPF_TEMPERROR=0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain 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 --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Document-M-x-align-in-the-Emacs-manual.patch >From 20fa3ea348617350fa8a437fad75aa9e9a9a620f Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH] Document 'M-x align' in the Emacs manual * doc/emacs/align.texi: New file. * doc/emacs/emacs.texi: Include it and update menu. --- doc/emacs/align.texi | 70 ++++++++++++++++++++++++++++++++++++++++++++ doc/emacs/emacs.texi | 2 ++ 2 files changed, 72 insertions(+) create mode 100644 doc/emacs/align.texi diff --git a/doc/emacs/align.texi b/doc/emacs/align.texi new file mode 100644 index 00000000000..c7e48890695 --- /dev/null +++ b/doc/emacs/align.texi @@ -0,0 +1,70 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2023 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Alignment +@chapter Alignment +@cindex 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. This is usually done 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 + +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. + +@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. 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 + +@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}. + +@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. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 7a21eb49e24..c4ed9a6ae93 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -178,6 +178,7 @@ Top Advanced Features * Modes:: Major and minor modes alter Emacs's basic behavior. * Indentation:: Editing the white space at the beginnings of lines. +* Alignment:: Making common parts of lines start at the same column. * Text:: Commands and modes for editing human languages. * Programs:: Commands and modes for editing programs. * Building:: Compiling, running and debugging programs. @@ -1616,6 +1617,7 @@ Intro @include mule.texi @include modes.texi @include indent.texi +@include align.texi @include text.texi @c Includes fortran-xtra. @include programs.texi -- 2.42.0 --=-=-=-- ------------=_1697282282-28201-1--