Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

I'm documenting a file containing several biblatex bibmacros and booleans and would like to create an index via \EnableCrossrefs, but

% \begin{macro}{mybibmacro}
%    \begin{macrocode}
\newbibmacro{mybibmacro}{}
%    \end{macro}

produces the entry

\mybibmacro

in the index and of course all further occurrences of mybibmacro in the code are ignored. Is there a way to avoid the leading backslash? Of course it would be perfect if future occurrences such as

\usebibmacro{mybibmacro}

would also be indexed under mybibmacro.

\newbool{mybool}

has exactly the same problem.

Combining this to a real example yields:

% \iffalse
\documentclass{ltxdoc}
\EnableCrossrefs         
\CodelineIndex
\begin{document}
  \DocInput{test.dtx}
\end{document}
% \fi
%
% \DescribeEnv{mybibmacro}
% This is my bibmacro.
%
% \DescribeMacro{mybool}
% The boolean \verb|mybool| will determine, if \verb|mybibmacro| is executed.
% 
% \StopEventually{\PrintIndex}
%
% \begin{macro}{mybool}
% Here we define the boolean.
%    \begin{macrocode}
\newbool{mybool}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{mybibmacro}
% Here we define the bibmacro.
%    \begin{macrocode}
\newbibmacro{mybibmacro}{}
%    \end{macrocode}
% \end{environment}
%
% Now the macro is executed depending on the status of \verb|mybool|. Ideally, both should be indexed as being used here.
%    \begin{macrocode}
\ifbool{mybool}{\usebibmacro{mybibmacro}}{}
%    \end{macrocode}
% 
% \Finale

Running this through latex and makeindex yields

Compiled dtx file with index

In the index mybool received a leading backslash and neither the usage of mybool nor of mybibmacro is indexed in line 3.

Also, the listing of mybibmacro under environments is slightly confusing, it might be good to get rid of that and of course optimal if one could add other categories in addition to environment (such as boolean, bibmacro etc.).

share|improve this question
add comment

1 Answer 1

up vote 10 down vote accepted

Probably you want to (ab)use or base something on \begin{environment} rather than \begin{macro} as that's not expecting the backslash form


First giving an extension working for environment usage as it is simpler, a more complete example in the next section.

here is an example modifying doc so that uses of \begin{foo} in macro code are not indexed as uses of \begin but as uses of the environment foo \end is automatically excluded from the index list.

test2.sty

\def\macro@finish{%
  \macro@namepart
\ifx\macro@namepart\xbegin
  \expandafter\macro@grabname
  \else  
\ifx\macro@namepart\xend
 \else
  \ifnot@excluded
     \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
     \@tempa  \fi
  \fi\fi}

\def\xbegin{begin}
\def\xbegin{end}
\begingroup
\lccode`\(`\{
\lccode`\)`\}
\lowercase{\endgroup
\def\macro@grabname\fi(#1){%
(#1)%
\SpecialEnvIndex{#1}%
}
}

test2.dtx

% \iffalse
\documentclass{ltxdoc}
\usepackage{test2}
\EnableCrossrefs         
\CodelineIndex
\begin{document}
  \DocInput{test2.dtx}
\end{document}
% \fi
%
% \DescribeMacro{\mymacro}
% Some meaningful description.
% 
% \StopEventually{\PrintIndex}
%
% \begin{macro}{\mymacro}
% Here we define the macro.
%    \begin{macrocode}
\newcommand{\mymacro}{hello}
%    \end{macrocode}
% \end{macro}

% \begin{environment}{myenv}
% Here we define the env.
%    \begin{macrocode}
\newenvironment{myenv}{\par[[[}{]]]\par}
%    \end{macrocode}
% \end{environment}
%
% And here we use it.
%    \begin{macrocode}
\PackageInfo{test2}{\mymacro}
%    \end{macrocode}
%    \begin{macrocode}
\def\foo{\begin{myenv}kkk\end{myenv}}
%    \end{macrocode}
% \clearpage
%    \begin{macrocode}
\def\foobar{\begin{myenv}jjj\end{myenv}}
%    \end{macrocode}
% 
% \Finale

Process this with:

pdflatex test2.dtx
makeindex -s gind.ist test2
pdflatex test2.dtx

Note that doc doesn't care about how a macro is defined just what it looks like, \begin{environment} starts a definition but shows the macro without a backslash and indexes it under "environment" (standard doc). The addition here is that begin{foo} gets indexed as an environment use. So if you have a package with a definition form for bibmacro you and a use as \newbibmacro you would need to copy the definitions of environment from doc, including the above extension, to a set of macros that are the same but with environment changed to bibmacro and \begin changed to \usebibmacro and then again for boolean or any other non-backslash define/use categories that you need.


Full BibLaTeX version

So, taking the above and then basically parameterising the environment code so it works for environment bibbool and bibmacro results in: enter image description here

testbool.dtx

% \iffalse
\documentclass{ltxdoc}
\usepackage{test2}
\EnableCrossrefs         
\CodelineIndex
\begin{document}
  \DocInput{testbool.dtx}
\end{document}
% \fi
%
% \DescribeBibMacro{mybibmacro}
% This is my bibmacro.
%
% \DescribeBibBool{mybool}
% The boolean \verb|mybool| will determine, if \verb|mybibmacro| is executed.
%
% \DescribeMacro{\texmacro}
% Checking I haven't broken the original
% indexing macros  for \verb|\texmacro|.
%
% \StopEventually{\PrintIndex}
%
% \begin{bibbool}{mybool}
% Here we define the boolean.
%    \begin{macrocode}
\newbool{mybool}
%    \end{macrocode}
% \end{bibbool}
%
% \begin{macro}{\texmacro}
% Here we define the boolean.
%    \begin{macrocode}
\def\texmacro{}
%    \end{macrocode}
% \end{macro}
%
% \begin{bibmacro}{mybibmacro}
% Here we define the bibmacro.
%    \begin{macrocode}
\newbibmacro{mybibmacro}{}
%    \end{macrocode}
% \end{bibmacro}
%
% Now the macro is executed depending on the status of \verb|mybool|. Ideally, both should be indexed as being used here.
%    \begin{macrocode}
\ifbool{mybool}{\usebibmacro{mybibmacro}}{}
%    \end{macrocode}
% 
%    \begin{macrocode}
\texmacro
%    \end{macrocode}
% 
% \Finale

test2.sty

\def\bibmacro{\def\macro@type{bibmacro}\environment}
\let\endbibmacro\endenvironment


\def\bibbool{\def\macro@type{bibbool}\environment}
\let\endbibbool\endenvironment

\def\macro@type{environment}%% default

\def\macro@finish{%
  \macro@namepart
\ifx\macro@namepart\xbegin
  \def\macro@type{environment}%
\else\ifx\macro@namepart\xifbool
   \def\macro@type{bibbool}%
   \let\macro@namepart\xbegin
\else\ifx\macro@namepart\xusebibmacro
 \def\macro@type{bibmacro}%
 \let\macro@namepart\xbegin
\fi\fi\fi
\ifx\macro@namepart\xbegin
  \expandafter\macro@grabname
  \else  
\ifx\macro@namepart\xend
 \else
  \ifnot@excluded
     \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
     \@tempa  \fi
  \fi\fi}

\def\xbegin{begin}
\def\xifbool{ifbool}
\def\xusebibmacro{usebibmacro}
\def\xend{end}
\begingroup
\lccode`\(`\{
\lccode`\)`\}
\lowercase{\endgroup
\def\macro@grabname\fi(#1){%
(#1)%
\SpecialxEnvUseIndex\macro@type{#1}%
}
}


\def\SpecialxEnvUseIndex#1{%
  \expandafter\SpecialxxEnvUseIndex\expandafter{#1}}

\def\SpecialxxEnvUseIndex#1#2{\@bsphack
    \special@index{#2\actualchar{\string\ttfamily\space#2}
           (#1)}%
    \special@index{#1s:\levelchar#2\actualchar{\string\ttfamily\space#2}}\@esphack}



\def\SpecialMainEnvIndex{%
   \expandafter\SpecialMainxEnvIndex\expandafter{\macro@type}}

\def\SpecialMainxEnvIndex#1#2{\@bsphack\special@index{%
                                      #2\actualchar
                                      {\string\ttfamily\space#2}
                                         (#1)%
                                      \encapchar main}%
    \special@index{#1s:\levelchar#2\actualchar{%
                   \string\ttfamily\space#2}\encapchar
           main}\@esphack}


\def\DescribeBibBool{%
\leavevmode\@bsphack\begingroup\MakePrivateLetters
\def\macro@type{bibbool}\begingroup\Describe@Env}

\def\DescribeBibMacro{%
\leavevmode\@bsphack\begingroup\MakePrivateLetters
\def\macro@type{bibmacro}\begingroup\Describe@Env}

\def\DescribeBibEnv{%
\leavevmode\@bsphack\begingroup\MakePrivateLetters
\def\macro@type{environment}\begingroup\Describe@Env}


\def\Describe@Env#1{\endgroup
              \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
              \SpecialEnvIndex{#1}\endgroup\@esphack\ignorespaces}

\def\SpecialEnvIndex{%
   \expandafter\SpecialxEnvIndex\expandafter{\macro@type}}

\def\SpecialxEnvIndex#1#2{\@bsphack
    \index{#2\actualchar{\string\ttfamily\space#2}
           (#1)\encapchar usage}%
    \index{#1s:\levelchar#2\actualchar{\string\ttfamily\space#2}\encapchar
           usage}\@esphack}
share|improve this answer
    
Thank you, I have updated my question providing an MWE that will hopefully clear things up. –  Jonathan Apr 16 '12 at 14:13
    
Perfect! Thank you very much! I don't quite understand why the definitions get a separate line for their entry in the respective category, but it more than does the job! –  Jonathan Apr 16 '12 at 23:43
1  
sorry there was a #1 that should be #2 while writing to the index file, this is fixed and test2.sty and the image updated –  David Carlisle Apr 17 '12 at 9:10
    
Why doesn't this work when I paste the content of the sty file into the header of the dtx file? I get the error ! Too many }'s. l.45 \fi\fi} (that's the last line of \macro@finish). It works with input so I really don't understand what could have happened .... –  Jonathan Apr 21 '12 at 17:10
1  
wel I think it's because of the doc package convention of guarding the top level document section with %\iffalse...\fi TeX's if-fi scanner needs to see balanced if-fi pairs but on the initial pass, the doc package hasn't been loaded so \ifnot@excluded isn't defined but the matching \fi is a primitive. There would be ways to avoid that but simplest is to keep it in a separate .sty :-) –  David Carlisle Apr 21 '12 at 19:17
show 1 more comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.