Discussion:
Odd error from index
Peter Flynn
2020-05-22 14:01:06 UTC
I just added hyperref to a class package under development, and suddenly
hit this error during the typesetting of the .dtx file, where it loads
(./test.ind
! LaTeX Error: Text for \verb command ended by end of line.
See the LaTeX manual or LaTeX Companion for explanation.
Type H <return> for immediate help.
...
l.7 \item |hyperpage\pfill 39
?
\begin{theindex}
{\bfseries\hfil Symbols\hfil}\nopagebreak
\item \verb*+\%+\pfill 212, 262
\item |hyperpage\pfill 39
The \% has been correctly indexed from the class code at lines 212 and
262. The \verb* command for \% appears to be formed correctly.

I have no idea what hyperpage is. Line 39 of the code is a perfectly
innocuous
\DeclareOption{legalpaper}{%
part of a slab of declarations for all the paper sizes within a
%␣␣␣␣\begin{macrocode}
...
%␣␣␣␣\end{macrocode}
block.

The whole thing works perfectly without the hyperref package. If I add
hyperref back in, I get the error.

1. What is "hyperpage" in the context of an index like this?

2. Before I start making a MWE, has anyone else hit this before?

Peter
Ulrike Fischer
2020-05-22 16:35:12 UTC
Post by Peter Flynn
I just added hyperref to a class package under development, and suddenly
hit this error during the typesetting of the .dtx file, where it loads
1. What is "hyperpage" in the context of an index like this?
it is used in the index to link that back to the page.
Post by Peter Flynn
2. Before I start making a MWE, has anyone else hit this before?
Try if it works if you load hypdoc.
--
Ulrike Fischer
https://www.troubleshooting-tex.de/
Peter Flynn
2020-05-23 00:30:54 UTC
Post by Ulrike Fischer
Post by Peter Flynn
I just added hyperref to a class package under development, and suddenly
hit this error during the typesetting of the .dtx file, where it loads
1. What is "hyperpage" in the context of an index like this?
it is used in the index to link that back to the page.
Post by Peter Flynn
2. Before I start making a MWE, has anyone else hit this before?
Try if it works if you load hypdoc.
That's great, many thanks.

Peter
Nicola Talbot
2020-05-22 18:03:07 UTC
Post by Peter Flynn
I just added hyperref to a class package under development, and suddenly
hit this error during the typesetting of the .dtx file, where it loads
(./test.ind
! LaTeX Error: Text for \verb command ended by end of line.
See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
... l.7   \item |hyperpage\pfill 39
?
Is the pipe character | a shortcut for \verb? (That would explain the
error message for the line shown in the transcript.) In which case, that
might be causing interference. (hyperref may be relying on a particular
category code of | when it appends |hyperpage to the indexing information.)

Regards
Nicola Talbot
--
Home: http://www.dickimaw-books.com/
Creating a LaTeX Minimal Example:
http://www.dickimaw-books.com/latex/minexample/
Peter Flynn
2020-05-24 12:10:30 UTC
[///]
Post by Nicola Talbot
... l.7   \item |hyperpage\pfill 39
Is the pipe character | a shortcut for \verb?
I think it's to avoid it. I found the problem:

On 22/05/2020 17:35, Ulrike Fischer wrote:
[...]
Post by Nicola Talbot
Try 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}

which then gives you this in the .gls file:

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

\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}

Peter
Nicola Talbot
2020-05-26 11:42:52 UTC
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 Talbot
Try 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/
Peter Flynn
2020-05-26 21:11:31 UTC
Post by Nicola Talbot
[...] I tested it by replacing the exclamation mark with a dot, and
everything is working fine.
The exclamation mark is a makeindex special character.
So I discovered; I hadn't expected it to need escaping in the actual
text of an entry, though.
Post by Nicola Talbot
[...] These style files change the default special characters, so you
need to be aware of these.
Yes, I use a custom gind.ist but I have only ever had to produce a
glossary once in my life :-) so I had never investigated gglo.ist.

Thanks so much for the example and explanation.
Post by Nicola Talbot
;-) I use \changes in .dtx files as well.
I don't think that will ever change :-)

Peter