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: