[Geiser-users] Errors in printed and Info references in the Geiser manual

[Mark Harig]

There are many examples in the Geiser manual in which the generated
HTML appears correct and readable, but in which the TeX (printed) and
Info version either don't follow the standard format (TeX) or the
result is ungrammatical (Info).

In some cases, the Texinfo code might be fixed by changing uses of the
@ref macro with the @xref or @pxref macro (See the node (texinfo)
Cross references).  In other cases, the sentence will need to be
rewritten in order to make the generated Info text grammatical.  (I'm
not sure that the goal of making the HTML links into readable text can
be made compatible with the requirements of the TeX (printed) and Info
versions.)

The list below is not a complete review of all references in the
Geiser manual.  I hope it is enough to provide a view of what the
problems are.


1) install.texi:

Texinfo source:
   That's it: you're ready to @ref{quick-start,,go}.

HTML: That's it: you're ready to go.

TeX: That's it: you're ready to [go], page 6.

   Error: Missing section name. Ungrammatical sentence.

Info: That's it: you're ready to see go.

   Error: "You're ready to see go." is ungrammatical.


2) repl.texi:

Texinfo source:
   (yes, you can stop the asking: see
   @ref{active-implementations,,below}).

HTML: (yes, you can stop the asking: see below).

TeX:  (yes, you can stop the asking: see [below], page 9).

   Error: Section name is missing.

Info: (yes, you can stop the asking: see below.).

   Error: Multiple periods.

Also, is "stop the asking" intended instead of "stop asking"?


3) repl.texi:

Texinfo source:

If that's not the case, you can tell Emacs where it is, as described
@ref{impl-binary,, below}.

HTML: If that's not the case, you can tell Emacs where it is, as
      described below.

TeX: If that's not the case, you can tell Emacs where it is, as
     described *note [below], page 9.

   Error: Section name is missing.
   Error: "...as described see [below]..." is ungrammatical.

Info: If that's not the case, you can tell Emacs where it is, as
      described *note below.

   Error: "...as described see below." is ungrammatical.


4) repl.texi:

Texinfo source:
   If worse comes to worst and the process is dead, @kbd{C-c C-z} will
   restart it (but the same shortcut, issued when the REPL is alive,
   will bring you back to the buffer you came from, as explained
   @ref{switching-repl-buff,,here}).

HTML:
   If worse comes to worst and the process is dead, C-c C-z will
   restart it (but the same shortcut, issued when the REPL is alive,
   will bring you back to the buffer you came from, as explained
   here).

TeX:
   If worse comes to worst and the process is dead, C-c C-z will
   restart it (but the same shortcut, issued when the REPL is alive,
   will bring you back to the buffer you came from, as explained
   [here], page 13).

   Error: Section name is missing.

Info:
   If worse comes to worst and the process is dead, C-c C-z will
   restart it (but the same shortcut, issued when the REPL is alive,
   will bring you back to the buffer you came from, as explained
   see here.).

   Error: "...as explained see here.)." is ungrammatical.


5) repl.texi:

Texinfo source:

   In tune with Geiser's @ref{current-module,,modus operandi},
   evaluations in the REPL take place in the namespace of the current
   module.

HTML:
   In tune with Geiser's modus operandi, evaluations in the REPL take
   place in the namespace of the current module.

TeX:
   In tune with Geiser's [modus operandi], page 1, evaluations
   in the REPL take place in the namespace of the current module.

   Error: Section name is missing.

Info:

   In tune with Geiser's *note modus operandi evaluations in the REPL
   take place in the namespace of the current module.

   Error: "In tune with Geiser's see modus operandi evaluations..." is
   ungrammatical.


6) repl.texi:

Texinfo source:
   The list of exported bindings is shown, again, in a buffer
   belonging to Geiser's documentation browser, where you have at your
   disposal a bunch of navigation commands listed in
   @xref{Documentation browser,,our cheat-sheet}. We'll have a bit
   more to say about the documentation browser in @xref{doc-browser,,a
   later section}.

HTML:
   The list of exported bindings is shown, again, in a buffer
   belonging to Geiser's documentation browser, where you have at your
   disposal a bunch of navigation commands listed in our
   cheat-sheet. We'll have a bit more to say about the documentation
   browser in a later section.

TeX:
   The list of exported bindings is shown, again, in a buffer
   belonging to Geiser's documentation browser, where you have at your
   disposal a bunch of navigation commands listed in See Section 5.3
   [our cheat-sheet], page 19. We'll have a bit more to say about the
   documentation browser in See [a later section], page 14.

   Error: "...listed in See Section..." is ungrammatical.
   Error: Section names do not match the actual section names.

Info:
   The list of exported bindings is shown, again, in a buffer
   belonging to Geiser's documentation browser, where you have at your
   disposal a bunch of navigation commands listed in our
   cheat-sheet. We'll have a bit more to say about the documentation
   browser in a later section.

- end of list -