Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
On Fri, 19 Apr 2024 22:56:13 +0200 pelzflorian (Florian Pelz) wrote --- > Hello Matt, pushed as 86fb0e039bf30cf85e2066401f9a384427c47ea8. > > I was bold enough to retain the xref change in (Setting Up the Daemon) > prompted by Ludo, because starting a sentence with @xref is recommended > in the Texinfo manual and its examples, while @pxref at the start of a > phrase is not preferrable, according to the “info "(texinfo)@pxref"”. > > Again, Texinfo cross-references are complicated. > > (In the German translations, I always wrote only @ref, but only because > @xref is not properly translated; Emacs in particular is not > internationalized at all.) Sounds good, thank you!
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hello Matt, pushed as 86fb0e039bf30cf85e2066401f9a384427c47ea8. I was bold enough to retain the xref change in (Setting Up the Daemon) prompted by Ludo, because starting a sentence with @xref is recommended in the Texinfo manual and its examples, while @pxref at the start of a phrase is not preferrable, according to the “info "(texinfo)@pxref"”. Again, Texinfo cross-references are complicated. (In the German translations, I always wrote only @ref, but only because @xref is not properly translated; Emacs in particular is not internationalized at all.) Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
On Tue, 16 Apr 2024 08:43:23 +0200 pelzflorian (Florian Pelz) wrote ---
> Hi Matt. When triple checking, I read in “info "(texinfo)@pxref"”:
>
>In past versions of Texinfo, it was not allowed to write punctuation
> after a '@pxref', so it could be used _only_ before a right parenthesis.
> This is no longer the case. The effect of '@pxref{NODE-NAME}' is
> similar to that of 'see @ref{NODE-NAME}'. However, in many circumstance
> the latter is preferrable, as this makes it clear in the Info output
> that the word "see" should be present.
>
> Because of this last sentence, my tendency would now be to use @pxref
> only for parentheses. (Texinfo is really confusing.) Should I just cut
> these changes:
>
> (Linux Services): Use @pxref to start phrase.
> (Configuring the Shell): Use @pxref to start phrase.
Yes, I agree that cutting those, and using the original "see @ref{}", is what
the Texinfo manual says is correct. We should also cut this change:
(Setting Up the Daemon): use @xref to start sentence.
The original was also correct.
The only change that should remain is:
(Build Systems): capitalize "python" and start parenthesized reference with
@pxref.
Thanks for checking that. I had it wrong and I learned something!
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hi Matt, Matt writes: > On Mon, 15 Apr 2024 14:58:50 +0200 pelzflorian (Florian Pelz) wrote > --- > > > Do you agree that I should commit your docs correction with @pxref? > > I believe it is an improvement over current “see @ref”, even though it > > looks different in the info reader. > > Yes, I agree and thank you for double checking. Sorry for not > answering you more clearly before! @pxref is the correct command to > use within parentheses. > > > I believe the Emacs errors are historical; looking at Emacs 29.3 as > > packaged in Guix, Emacs-Info displays xref properly as See. Display > > errors had existed, but in the past only. > > I reported it to emacs-devel (it's addressed now) and the issue isn't > technically @xrefs; it's the compilation of @xref and @ref, '*Note' > and '*note' respectively. Emacs looks at the context around these and > renders them as 'See' or 'see' according to what's nearby. The > trouble is that the Texinfo documentation intends to show '*Note' and > '*note' literally which is an exception to the Emacs logic. > > I looked it up and the related Emacs code had been there for like 18 > years...I have a knack for finding these kinds of dumb things. I > can't decide if it's a superpower or a super-curse. :) Awesome! Definitely a superpower in my book. Thanks for following it through with the Emacs folks! I'm sure I was bothered by that inconsistency before but couldn't put my finger on the culprit. -- Thanks, Maxim
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hi Matt. When triple checking, I read in “info "(texinfo)@pxref"”:
In past versions of Texinfo, it was not allowed to write punctuation
after a '@pxref', so it could be used _only_ before a right parenthesis.
This is no longer the case. The effect of '@pxref{NODE-NAME}' is
similar to that of 'see @ref{NODE-NAME}'. However, in many circumstance
the latter is preferrable, as this makes it clear in the Info output
that the word "see" should be present.
Because of this last sentence, my tendency would now be to use @pxref
only for parentheses. (Texinfo is really confusing.) Should I just cut
these changes:
(Linux Services): Use @pxref to start phrase.
(Configuring the Shell): Use @pxref to start phrase.
or is there more that should go in this patch?
Matt writes:
> On Mon, 15 Apr 2024 14:58:50 +0200 pelzflorian (Florian Pelz) wrote
> ---
> > I believe the Emacs errors are historical; looking at Emacs 29.3 as
> > packaged in Guix, Emacs-Info displays xref properly as See. Display
> > errors had existed, but in the past only.
>
> I reported it to emacs-devel (it's addressed now) and the issue isn't
> technically @xrefs; it's the compilation of @xref and @ref, '*Note'
> and '*note' respectively. Emacs looks at the context around these and
> renders them as 'See' or 'see' according to what's nearby. […]
Ohh thank you and them for the fix.
Regards,
Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
On Mon, 15 Apr 2024 14:58:50 +0200 pelzflorian (Florian Pelz) wrote --- > Do you agree that I should commit your docs correction with @pxref? > I believe it is an improvement over current “see @ref”, even though it > looks different in the info reader. Yes, I agree and thank you for double checking. Sorry for not answering you more clearly before! @pxref is the correct command to use within parentheses. > I believe the Emacs errors are historical; looking at Emacs 29.3 as > packaged in Guix, Emacs-Info displays xref properly as See. Display > errors had existed, but in the past only. I reported it to emacs-devel (it's addressed now) and the issue isn't technically @xrefs; it's the compilation of @xref and @ref, '*Note' and '*note' respectively. Emacs looks at the context around these and renders them as 'See' or 'see' according to what's nearby. The trouble is that the Texinfo documentation intends to show '*Note' and '*note' literally which is an exception to the Emacs logic. I looked it up and the related Emacs code had been there for like 18 years...I have a knack for finding these kinds of dumb things. I can't decide if it's a superpower or a super-curse. :) > Again thank you for tediously working through deficiencies in Guix’ docs. Like Richard Hamming asks, "If what you're working on is not important and it's not likely to lead to important things, why are you working on it?" I think Guix is important! Thanks for sticking with me :)
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Matt writes: > The problem is that the Emacs Info reader incorrectly renders > cross-references by default. I was reading the Texinfo documentation > in Emacs. I believe the Emacs errors are historical; looking at Emacs 29.3 as packaged in Guix, Emacs-Info displays xref properly as See. Display errors had existed, but in the past only. Again thank you for tediously working through deficiencies in Guix’ docs. Do you agree that I should commit your docs correction with @pxref? I believe it is an improvement over current “see @ref”, even though it looks different in the info reader. Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
On Sat, 13 Apr 2024 13:26:39 +0200 pelzflorian (Florian Pelz) wrote --- > @xref produces a capital See instead of see. This should be @pxref. > See the Texinfo manual “info texinfo” or the Web manual Ludo points to. > > In info, this will use the word *note instead of *see, but it’s still > right, if Matt you agree. Yes, rereading the linked docs, it is as you say. The problem is that the Emacs Info reader incorrectly renders cross-references by default. I was reading the Texinfo documentation in Emacs. The default Emacs rendering of the Texinfo info file looks like: #+begin_src info ‘@xref’ Used to start a sentence with an Info cross-reference saying ‘see NAME.’ or with 'See ...' in other output formats. ‘@ref’ Used within or, more often, at the end of a sentence; produces an Info cross-reference saying ‘see NAME.’, and just the reference in other output formats, without the preceding 'See'. #+end_src Specifically, it misleadingly replaces info file instances of "*Note", which correspond to @xref, with (lowercase 's') "see ". A workaround is use (setq Info-hide-note-references nil) I was unable to fix the issue in Emacs and have filed a bug report. > Additionally, the commit message’s first sentence should end with a > period. The sentences in the commit message describing a section should > start with a capital letter. Thank you for the reminder. I have made a note to check this for my future submissions.
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Matt writes: > The attached change updates "Libera Chat" to the "Libera.Chat" stylization. Pushed as df7b569b464c05036871f23d37ba319be78e5f64. Thanks! Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hello,
I just want to mention that I am still in CC and my mail server is going
offline. Need to optimize my budget and don't have any time for GNU
anymore because of university.
--
Christian Miller
Am 10/04/2024 um 16:05 schrieb Matt:
We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html
We have completed the first two items.
The next item reported is:
#+begin_quote
2.4 Setting up the deamon
Seems like an issue with info. Have seen this in the Emacs manual as well.
There is also sometimes see see (doc)
L15 See also see Substitutes.
#+end_quote
This sounds like the use of an @xref instead of @ref. However, I can't find it
in the current version (5a95cf76) of the documentation, nor the reported
version (ee7c9d25). The last change to doc/guix.texi at that the reported time
was in e5ed1712 (git log -n 1 ee7c9d25 -- doc/guix.texi).
The full reported sentence currently reads,
#+begin_quote
See also @ref{Substitutes}, for information on how to allow the daemon to
download pre-built binaries.
#+end_quote
The use of the comma after "Substitutes" is inappropriate, if I have the terminology correct, because
"See also Substitutes" is not a participial phrase. "Also" and "information on" are also
unnecessary. I suggest the following:
#+begin_quote
See @ref{Substitutes} for how to allow the daemon to download pre-built
binaries.
#+end_quote
Searching for "see also" turns up the following in 'Mail Services':
#+begin_quote
See also ssl=required setting.
#+end_quote
This needs "the" before "ssl=required" as it refers to a specific setting. It
should probably use the @option or @samp markup:
#+begin_quote
See also the @samp{ssl=required} setting.
#+end_quote
I have opted for @samp because it's used elsewhere for similar items. In the
same section is:
#+begin_quote
NOTE: See also @samp{disable-plaintext-auth} setting.
#+end_quote
This too should have "the" before the setting. The "NOTE:" designation is also
unnecessary. I suggest:
#+begin_quote
See also the @samp{disable-plaintext-auth} setting.
#+end_quote
Included is a patch which makes these suggested changes.
It was advised to submit the previous patch to guix-patches. I opted to submit
this next patch here to keep the thread connected since it's part of a larger
discussion (I suppose). If we're agreed that guix-patches is more appropriate,
I can submit the next item in a new thread there using the same message format
I've been following. Thoughts?
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Matt writes:
> #+begin_quote
> 3.7 After System Installation
> L27 Libera_Chat, why the underscore. It is colored as well for me so
> I guess this is a special char. Should be anways just Libera Chat
> #+end_quote
>
> "Libera_Chat" is not, or no longer, in the docs (d3fe763fe3).
> However, there are two variations present: "Libera Chat" and
> "Libera.Chat".
Currently Libera Chat is written using a non-breaking space. We could
also use @tie{} instead of the special char . I do agree with your
Libera.Chat stylization, will push it later. It will not matter to
search engines, I think.
Regards,
Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hello Matt. Thank you for fixing the oversight. However: Matt writes: > From: Matthew Trzcinski > Date: Sat, 13 Apr 2024 10:12:05 +0200 > Subject: [PATCH] doc: Fix cross-references > > * doc/guix.texi (Setting Up the Daemon): use @xref to start sentence. > (Build Systems): capitalize "python" and start parenthesized reference with > @pxref. > (Linux Services): use @xref to start phrase. @xref produces a capital See instead of see. This should be @pxref. See the Texinfo manual “info texinfo” or the Web manual Ludo points to. In info, this will use the word *note instead of *see, but it’s still right, if Matt you agree. > (Configuring the Shell): use @xref to start phrase. This should be @pxref. Additionally, the commit message’s first sentence should end with a period. The sentences in the commit message describing a section should start with a capital letter. Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
On Fri, 12 Apr 2024 22:16:39 +0200 Ludovic Courtès wrote ---
> > See @ref{Substitutes} for how to allow the daemon to download pre-built
> > binaries.
>
> Nitpick: this works but I believe the recommended approach is
> “@xref{Substitutes} for how…”.
>
>
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html
Good catch! I took the opportunity and found several similar issues elsewhere.
The attached patch tries to correct them.
> Thanks for reporting these issues!
I appreciate your assistance with these details :)
0001-doc-Fix-cross-references.patch
Description: Binary data
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hi,
Matt skribis:
> See @ref{Substitutes} for how to allow the daemon to download pre-built
> binaries.
Nitpick: this works but I believe the recommended approach is
“@xref{Substitutes} for how…”.
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html
Thanks for reporting these issues!
Ludo’.
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
We're working through a list of feedback one item at a time: https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html We have completed the first three items. The next item reported is: #+begin_quote 3.7 After System Installation L27 Libera_Chat, why the underscore. It is colored as well for me so I guess this is a special char. Should be anways just Libera Chat #+end_quote "Libera_Chat" is not, or no longer, in the docs (d3fe763fe3). However, there are two variations present: "Libera Chat" and "Libera.Chat". The attached change updates "Libera Chat" to the "Libera.Chat" stylization. The network itself is inconsistent in self-reference and provides no guideline I could find on which form to use. I opted for the "dot" version to make things consistent. Because the URL is https://libera.chat, someone searching for the network by copy-paste may arrive at the homepage more directly than with the non-dot version. 0001-doc-Standardize-IRC-stylization.patch Description: Binary data
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Pushed as cd557e2d1c83839dd587016279900d31f053efc8. Matt writes: > The next item reported is: > > #+begin_quote > 2.4 Setting up the deamon > > Seems like an issue with info. Have seen this in the Emacs manual as well. > There is also sometimes see see (doc) > > L15 See also see Substitutes. > #+end_quote > > > This sounds like the use of an @xref instead of @ref. However, I > can't find it in the current version (5a95cf76) of the documentation, > nor the reported version (ee7c9d25). […] I believe the rendering of @ref was an issue with Emacs that is gone in latest Emacs. > It was advised to submit the previous patch to guix-patches. I opted > to submit this next patch here to keep the thread connected since it's > part of a larger discussion (I suppose). If we're agreed that > guix-patches is more appropriate, I can submit the next item in a new > thread there using the same message format I've been following. > Thoughts? I believe guix-devel is OK for such changes. Regards, Florian
