Does DocStrip dislike glossaries?

Question

I had a rather nice idea, pop any glossary terms into a DTX file. I can partition any terms by domain/topic into styles files called domain.sty/topic.sty and load whatever is relevant. So I run through the check list

• DTX - Copied and modified from the dtxtut docs of Mr. Pakin
• INS - Copied and modified from the dtxtut docs of Mr. Pakin
• STY - Generated from said sources
• Glossary in DTX generated documentation ... NO ?

I had a quick eye ball at the glossaries.dtx but it seems they don't include a glossary... ironic really. So it's wiMoWE time ("Well it's Minimal only (not) Working Example" sung to the tune of in the jungle...).

I have attached a complete example.dtx and example.ins which ought to produce a example.pdf along with an example.sty file with various example.glo/gls/ind/idx glossary files. The astute compiler may notice the creation of example.egn/egd/egg files these are due to the "\newglossary" created in the sty file and are generated when you compile the dtx file.

The compilation procedure followed is

pdflatex example.idx
makeglossaries example

to which I get the error

Package glossaries Warning: No file defined for glossary `[' on input line 86.
! Extra \endcsname.
\@@do@wrglossary ...\csname glo@#1@type\endcsname
                                                  ]{\string \glossaryentry {...
l.86 ...lossary type. It has a single \gls{entry}
                                                  in it.

The error disappears if one comments out the \gls{...} call on line 86, though you don't get a glossary entry either then. Curiously in my original code I've tried using \glsaddall which threw a similar error. The style files work well when called in other documents it's just back referencing to the DTX source that doesn't work, perhaps texdoc is a little fussy ?

Example.dtx

 % \iffalse meta-comment
 %
 % Copyright (C) XXXX by Carel <[email protected]>
 % ----------------------------------------
 % 
 % This file may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.2
 % of this license or (at your option) any later version.
 % The latest version of this license is in:
 %
 %    http://www.latex-project.org/lppl.txt
 %
 % and version 1.2 or later is part of all distributions of LaTeX 
 % version 1999/12/01 or later.
 %
 % \fi
 %
 % \iffalse
 %<*driver>
 \ProvidesFile{example.dtx}
 %</driver>
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{example}
 %<*package>
     [2004/11/05 v1.0 .dtx example file]
 %</package>
 %
 %<*driver>
 \documentclass{ltxdoc}
 \usepackage[nomain]{glossaries}
 \usepackage{example}[2004/11/05]
 \EnableCrossrefs         
 \CodelineIndex
 \RecordChanges
 \makeglossaries
 \begin{document}
   \DocInput{example.dtx}
   \PrintChanges
   \PrintIndex
 \end{document}
 %</driver>
 % \fi
 %
 % \CheckSum{0}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
 %   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
 %   Digits        \0\1\2\3\4\5\6\7\8\9
 %   Exclamation   \!     Double quote  \"     Hash (number) \#
 %   Dollar        \$     Percent       \%     Ampersand     \&
 %   Acute accent  \'     Left paren    \(     Right paren   \)
 %   Asterisk      \*     Plus          \+     Comma         \,
 %   Minus         \-     Point         \.     Solidus       \/
 %   Colon         \:     Semicolon     \;     Less than     \<
 %   Equals        \=     Greater than  \>     Question mark \?
 %   Commercial at \@     Left bracket  \[     Backslash     \\
 %   Right bracket \]     Circumflex    \^     Underscore    \_
 %   Grave accent  \`     Left brace    \{     Vertical bar  \|
 %   Right brace   \}     Tilde         \~}
 %
 %
 % \changes{v1.0}{2004/11/05}{Initial version}
 %
 % \GetFileInfo{example.dtx}
 %
 % \DoNotIndex{\newcommand,\newenvironment}
 % 
 %
 % \title{The \textsf{Example} package\thanks{This document
 %   corresponds to \textsf{example}~\fileversion, dated \filedate.}}
 % \author{Carel \\ \texttt{[email protected]}}
 %
 % \maketitle
 %
 % \section{Introduction}
 %
 % Put text here.
 %
 % \section{Usage}
 %
 % Put text here.
 %
 % \DescribeEnv{notes}
 %  
 % Notes is an example glossary type. It has a single \gls{entry} in it.
 %
 % \StopEventually{}
 %
 % \section{Implementation}
 %
 % \begin{environment}{notes}
 % I define an example glossary environment called |notes|.
 %    \begin{macrocode}
 \newglossary[egg]{example}{egd}{egn}{Example glossary}
 %    \end{macrocode}
 % \end{environment}
 %
 % \begin{macro}{notes}
 % I define a single entry in the new glossary format
 %    \begin{macrocode}
 \newglossaryentry{entry}{
  name        = entry,
  type        = example,
  description = An example entry in notes,
 }
 %    \end{macrocode}
 % \end{macro}
 %
 % \Finale
 \endinput

Example.ins

 %%
 %% Copyright (C) XXXX by carel <[email protected]>
 %%
 %% This file may be distributed and/or modified under the conditions of
 %% the LaTeX Project Public License, either version 1.2 of this license
 %% or (at your option) any later version.  The latest version of this
 %% license is in:
 %% 
 %%    http://www.latex-project.org/lppl.txt
 %% 
 %% and version 1.2 or later is part of all distributions of LaTeX version
 %% 1999/12/01 or later.
 %%

 \input docstrip.tex
 \keepsilent

 \usedir{tex/latex/example}

 \preamble

 This is a generated file.

 Copyright (C) XXXX by carel <[email protected]>

 This file may be distributed and/or modified under the conditions of
 the LaTeX Project Public License, either version 1.2 of this license
 or (at your option) any later version.  The latest version of this
 license is in:

    http://www.latex-project.org/lppl.txt

 and version 1.2 or later is part of all distributions of LaTeX version
 1999/12/01 or later.

 \endpreamble

 \generate{\file{example.sty}{\from{example.dtx}{package}}}

 \obeyspaces
 \Msg{*************************************************************}
 \Msg{*                                                           *}
 \Msg{* To finish the installation you have to move the following *}
 \Msg{* file into a directory searched by TeX:                    *}
 \Msg{*                                                           *}
 \Msg{*     skeleton.sty                                          *}
 \Msg{*                                                           *}
 \Msg{* To produce the documentation run the file skeleton.dtx    *}
 \Msg{* through LaTeX.                                            *}
 \Msg{*                                                           *}
 \Msg{* Happy TeXing!                                             *}
 \Msg{*                                                           *}
 \Msg{*************************************************************}

 \endbatchfile

(Note : The command "texdoc --view PACKAGE" returns the documentation for PACKAGE, a most useful yet unadvertised command, "texdoc --view dtxtut" will provide Mr. Pakins tutorial)

Update : Why ?

All my dtx files reside in one folder containing subfolders whose names correspond to the dtx files. I have junctioned/linked these into the TeX Directory Structure (TDS) so updating a macro simply involves recompiling the DTX's. New packages simply require a duplicating my DTX template, building and linking the built directory to the TDS and refreshing the File Name Database (FNDB) (I'm on MikTex). Making my glossaries into packages means I don't have junctions everywhere between my documents and my glossaries. I can simply \usepackage{Glossary} and tex sorts out the searching for me. Additionally I could readily compile all my terms into the package doc for quick reference. I suppose distribution becomes easier aswell, mail the dtx. Version control also becomes more fine grained, if that's your thing, one could commit after every new definition.

Related :

My actual DTX is a bit more complex then what is shown in the MWE and I found the related post also relevant.

Answer 1

I adapted your source to really be Example.dtx and Example.ins since there's already an example.sty in standard TeX distributions.

Example.dtx:

% \iffalse meta-comment
%
% Copyright (C) XXXX by Carel <[email protected]>
% ----------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{Example.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{Example}
%<*package>
   [2004/11/05 v1.0 .dtx Example file]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[nomain]{glossaries}
\usepackage{Example}[2004/11/05]
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\makeglossaries
\begin{document}
 \DocInput{Example.dtx}
 \PrintChanges
 \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{2004/11/05}{Initial version}
%
% \GetFileInfo{Example.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
%
% \title{The \textsf{Example} package\thanks{This document
%   corresponds to \textsf{Example}~\fileversion, dated \filedate.}}
% \author{Carel \\ \texttt{[email protected]}}
%
% \maketitle
%
% \section{Introduction}
%
% Put text here.
%
% \section{Usage}
%
% Put text here.
%
% \DescribeEnv{notes}
%
% Notes is an example glossary type. It has a single \gls{entry} in it.
%
% \StopEventually{}
%
% \section{Implementation}
%
% \begin{environment}{notes}
% I define an example glossary environment called |notes|.
%    \begin{macrocode}
\newglossary[egg]{example}{egd}{egn}{Example glossary}
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{notes}
% I define a single entry in the new glossary format
%    \begin{macrocode}
\newglossaryentry{entry}{
name        = entry,
type        = example,
description = An example entry in notes,
}
%    \end{macrocode}
% \end{macro}
%
% \printglossaries% added for testing purposes - just to be sure
%
% \Finale
\endinput

Example.ins:

%%
%% Copyright (C) XXXX by carel <[email protected]>
%%
%% This file may be distributed and/or modified under the conditions of
%% the LaTeX Project Public License, either version 1.2 of this license
%% or (at your option) any later version.  The latest version of this
%% license is in:
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% and version 1.2 or later is part of all distributions of LaTeX version
%% 1999/12/01 or later.
%%

\input docstrip.tex
\keepsilent

\usedir{tex/latex/example}

\preamble

This is a generated file.

Copyright (C) XXXX by carel <[email protected]>

This file may be distributed and/or modified under the conditions of
the LaTeX Project Public License, either version 1.2 of this license
or (at your option) any later version.  The latest version of this
license is in:

  http://www.latex-project.org/lppl.txt

and version 1.2 or later is part of all distributions of LaTeX version
1999/12/01 or later.

\endpreamble

\generate{\file{Example.sty}{\from{Example.dtx}{package}}}

\obeyspaces
\Msg{*************************************************************}
\Msg{*                                                           *}
\Msg{* To finish the installation you have to move the following *}
\Msg{* file into a directory searched by TeX:                    *}
\Msg{*                                                           *}
\Msg{*     Example.sty                                           *}
\Msg{*                                                           *}
\Msg{* To produce the documentation run the file Example.dtx     *}
\Msg{* through LaTeX.                                            *}
\Msg{*                                                           *}
\Msg{* Happy TeXing!                                             *}
\Msg{*                                                           *}
\Msg{*************************************************************}

\endbatchfile

This produces the following Example.sty:

%%
%% This is file `Example.sty',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% Example.dtx  (with options: `package')
%% 
%% This is a generated file.
%% 
%% Copyright (C) XXXX by carel <[email protected]>
%% 
%% This file may be distributed and/or modified under the conditions of
%% the LaTeX Project Public License, either version 1.2 of this license
%% or (at your option) any later version.  The latest version of this
%% license is in:
%% 
%%   http://www.latex-project.org/lppl.txt
%% 
%% and version 1.2 or later is part of all distributions of LaTeX version
%% 1999/12/01 or later.
%% 
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{Example}
   [2004/11/05 v1.0 .dtx Example file]
\newglossary[egg]{example}{egd}{egn}{Example glossary}
\newglossaryentry{entry}{
name        = entry,
type        = example,
description = An example entry in notes,
}
\endinput
%%
%% End of file `Example.sty'.

and the following documentation:

If you are using a case-insensitive file system, you should use some other name than Example as it may otherwise be conflated with example in unpredictable ways.

So it all seems to work. That said, I'm not entirely sure why you are doing it this way. That is, why all the messing around with .dtx and .ins when you just want to create a glossary as far as I can tell? The glossaries package already allows you to keep databases of glossary entries in simple .tex format. I have a whole bunch by topic and can then just load the ones I need. And if I add new entries or change them, those are immediately available - no need to mess around regenerating .sty file.

The .dtx/.ins stuff is designed to aid in distributing packages but even if you are distributing your topic glossaries, wouldn't a simple archive of .tex glossary files be simpler all round?