Re: jitter.texi

[Luca Saiu]

On 2025-05-21 at 14:12 +0000, Jose E. Marchesi wrote:

> Seems like the jitter.texi file shipped with poke contains some Texinfo
> that triggers an error in `make pdf':
>
> ./jitter.cps:1: Argument of @asis has an extra }.

Replying here for the benefit of those who search the archives, and
those who were not present at our IRC discussion with Mark and Mohammad:

The symptom above was the effect of two separate Texinfo problems, one
in the Jitter manual and another in the Poke manual, both having to do
with the index.

The problem is using @cindex with a macro as an argument.  According to
the Texinfo documentation some macros are clearly supported:

       By default, entries for a concept index are printed in a roman font
    and entries for the other indices are printed in a typewriter font.  You
    may change the way part of an entry is printed with the usual Texinfo
    commands, such as ‘@file’ for file names (*note Marking Text::), and
    ‘@r’ for the normal roman font (*note Fonts::).

However one should not use a user macro inside an index entry:

       • Texinfo commands in the expansion of a macro in the text of an
         index entry may end up being typeset as literal text (including an
         "@" sign), instead of being interpreted with their intended
         meaning.

My symptom was in fact more serious than just the macro name appearing
in the index instead of its expansion.

My entries were looking like

@cindex @epsilonzero{}

where @epsilonzero{} is a macro of mine.  Surprisingly, its definition
turned out not to matter.

In the Poke manual instead there was

@cindex @code{@?}

which failed because ? does not need to be escaped in Texinfo.  The
symptom was the same obscure reference to @asis , that was not used
explicitly in either manual.

--  
Luca Saiu      https://ageinghacker.net
  GNU Jitter     https://www.gnu.org/software/jitter
  GNU epsilon    https://www.gnu.org/software/epsilon
  pEp-mail-tool  https://codeberg.org/pEp/pEp-mail-tool

I support everyone's freedom of mocking any opinion or belief, no
matter how deeply held, with open disrespect and the same unrelented
enthusiasm of a toddler who has just learned the word "poo".

sender_key.asc
Description: application/pgp-keys