From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eshel Yaron via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Date: Thu, 05 Oct 2023 12:46:24 +0200 Message-ID: References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> Reply-To: Eshel Yaron Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="18278"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 66303@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Oct 05 12:47:13 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qoLsu-0004Sw-7V for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 05 Oct 2023 12:47:12 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qoLsY-0000Ut-4z; Thu, 05 Oct 2023 06:46:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qoLsS-0000Cg-Dd for bug-gnu-emacs@gnu.org; Thu, 05 Oct 2023 06:46:46 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qoLsR-0002S3-GY for bug-gnu-emacs@gnu.org; Thu, 05 Oct 2023 06:46:43 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qoLsj-0002LY-Jy for bug-gnu-emacs@gnu.org; Thu, 05 Oct 2023 06:47:01 -0400 X-Loop: help-debbugs@gnu.org 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 Original-Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.16965028149006 (code B ref 66303); Thu, 05 Oct 2023 10:47:01 +0000 Original-Received: (at 66303) by debbugs.gnu.org; 5 Oct 2023 10:46:54 +0000 Original-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 Original-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== In-Reply-To: <83edi94ic9.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 05 Oct 2023 10:52:06 +0300") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:271863 Archived-At: --=-=-= 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 --=-=-=--