Post by Peter Flynn[///]
Post by Nicola Talbot ... l.7 \item |hyperpage\pfill 39
Is the pipe character | a shortcut for \verb?
[...]
Post by Nicola TalbotTry if it works if you load hypdoc.
That helps, but the problem appears to be reproducible if in a .dtx file
you have a \changes command whose third argument ends in an exclamation
mark, eg
% \changes{v1.18}{2020/04/01}{Updated all master documents!}
From this you get the entry in the .glo file
\glossaryentry{v1.18> =General:>Updated all master
documents!|hdpindex{}}{21}
\subsubitem Updated all master documents|hdpindex{}\pfill 21
Notice that the exclamation mark has disappeared.
My original problem was with the index, with the line
\item |hyperpage\pfill 39
which is long since gone (when I get time, I shall burrow back through
the versions to see if there was an exclamation mark there at some
stage), but as this glossary exhibits the same error (Text for \verb
command ended by end of line.) I tested it by replacing the exclamation
mark with a dot, and everything is working fine.
The exclamation mark is a makeindex special character. It needs to be
escaped (using makeindex's escape character, which defaults to " but may
be changed in the .ist file). So you would normally need "! for an
exclamation mark, but when indexing in .dtx files it's typical to use
gglo.ist for \changes and gind.ist for the index. These style files
change the default special characters, so you need to be aware of these.
Both gind.ist and gglo.ist contain:
actual '='
quote '!'
level '>'
For reference, the default definitions are:
actual '@'
quote '"'
level '!'
encap '|'
The encap isn't changed in gind.ist/gglo.ist so it's still the default
pipe character (|).
The exclamation mark is still a special character but it's changed from
being the level character to the quote character. This means that if you
want to escape a special character you need to put ! in front of it, so
for a literal exclamation mark you now need !! (instead of "!).
By way of example, consider the simple document (not a .dtx file):
\documentclass{article}
\usepackage{doc}
\RecordChanges
\begin{document}
Test\changes{2020-05-26}{1.0}{change test!}
\end{document}
(assume this file is called test.tex)
This creates the test.glo file containing:
\glossaryentry{2020-05-26> =General:>change test!}{1}
Run makeindex -s gglo.ist -o test.gls test.glo
This results in the error message:
Scanning input file test.glo...done (0 entries accepted, 1 rejected).
The transcript file contains further details:
!! Input index error (file = test.glo, line = 1):
-- Incomplete first argument (premature LFD).
Now that ! is the quote character, it means that the following character
should be treated literally, but the following character is the closing
brace that terminates the first argument of \glossaryentry. So there's a
syntax error. The correct syntax is:
\changes{2020-05-26}{1.0}{change test!!}
Below is a slight modification to the document that can be used to
demonstrate the differences between just using doc.sty, using
doc.sty+hyperref.sty and using hypdoc.sty (which internally loads both
doc.sty and hyperref.sty):
Just doc.sty:
\documentclass{article}
\usepackage{doc}
\RecordChanges
\PageIndex
\begin{document}
Test\changes{2020-05-26}{1.0}{change test}
\index{index test}
\DescribeMacro\test
\end{document}
The test.glo file contains:
\glossaryentry{2020-05-26> =General:>change test}{1}
The test.idx file contains:
\indexentry{index test}{1}
\indexentry{test=\verb!*+\test+|usage}{1}
So \DescribeMacro automatically adds the encap (|usage) and uses the
actual character (=) to provide a sort value (test) that's different to
the actual value (\verb*+\test+).
Now add \usepackage{hyperref} after \usepackage{doc}. There's no change
to the test.glo file but the test.idx file now has a syntax error:
\indexentry{index test|hyperpage}{1}
\indexentry{test=\verb!*+\test+|usage|hyperpage}{1}
(makeindex doesn't permit multiple encaps). This is because hyperref
automatically appends |hyperpage to the contents of \index to ensure the
page numbers in the index are hyperlinks.
Now replace the two \usepackage lines with just \usepackage{hypdoc}. The
test.glo file now contains:
\glossaryentry{2020-05-26> =General:>change test|hdpindex{}}{1}
and the test.idx file now contains:
\indexentry{index test}{1}
\indexentry{test=\verb!*+\test+|hdclindex{2}{usage}}{1}
so now there's no syntax error, but note that the \index reference won't
have a hyperlink for the page number as there's no encap. If you need to
explicitly use \index (rather than just using commands like
\DescribeMacro) then you'd need to add the hyperpage encap. For example
\index{test|hyperpage}.
Your original post identified a problem with line 7 of your index (.ind)
Post by Peter Flynn... l.7 \item |hyperpage\pfill 39
This can be reproduced with:
\documentclass{article}
\usepackage{doc}
\usepackage{hyperref}
\RecordChanges
\PageIndex
\begin{document}
Test\index{!}
\PrintIndex
\end{document}
Because hyperref automatically appends |hyperpage this means that the
entry is written to the .idx file as:
\indexentry{!|hyperpage}{1}
This is interpreted by makeindex as a literal pipe followed by
"hyperpage" so that's what it writes to the .ind file. This would
normally result in a strange "|hyperpage" term appearing in the index
(which may appear as "—hyperpage", depending on the font). The error
message:
! LaTeX Error: Text for \verb command ended by end of line.
which occurs when LaTeX is parsing this line suggests that | has been
turned into a shortcut for \verb|
\MakeShortVerb{|}
so the line effectively becomes:
\item \verb|hyperpage\pfill
which is missing the matching | character required to terminate the
argument of \verb.
In general, odd results in indexing usually stem from makeindex's
special characters or by automatically appending an encap to indexing
content that may already contain one.
Post by Peter Flynn\begin{grovel}
And no, Nicola, it's not using glossaries, which it should be :-)
But that would require surgery on code on Deck 1.
\end{grovel}
;-) I use \changes in .dtx files as well.
Best regards
Nicola
--
Home: http://www.dickimaw-books.com/
Creating a LaTeX Minimal Example:
http://www.dickimaw-books.com/latex/minexample/