From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Date: Sat, 07 Oct 2023 10:26:16 +0300 Message-ID: <83bkda28rr.fsf@gnu.org> References: <83wmw56md7.fsf@gnu.org> <83edi94ic9.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35596"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 66303@debbugs.gnu.org To: Eshel Yaron Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Oct 07 09:26:59 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 1qp1iF-00093e-8D for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 07 Oct 2023 09:26:59 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qp1i1-0003ss-VT; Sat, 07 Oct 2023 03:26:45 -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 1qp1i0-0003sk-3Z for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2023 03:26:44 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qp1hy-0004kb-UY for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2023 03:26:43 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qp1iH-00030a-PF for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2023 03:27:01 -0400 X-Loop: help-debbugs@gnu.org 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 Original-Received: via spool by 66303-submit@debbugs.gnu.org id=B66303.169666359811528 (code B ref 66303); Sat, 07 Oct 2023 07:27:01 +0000 Original-Received: (at 66303) by debbugs.gnu.org; 7 Oct 2023 07:26:38 +0000 Original-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 Original-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 Original-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==; In-Reply-To: (message from Eshel Yaron on Thu, 05 Oct 2023 12:46:24 +0200) 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:271979 Archived-At: > 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.