Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

 ---- 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.