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.

So, I'm creating a rather big project in LaTeX and we've got our own API defined, so my current job is to create MAN-like pages for each API function in LaTeX. The standard format we use for each function is:

\bmumansection{NAME}{%<*NAME>
%text here
%</NAME>
}
\bmumansection{SYNOPSIS}{%<*SYNOPSIS>
%text here
%</SYNOPSIS>
}
\bmumansection{DESCRIPTION}{%<*DESCRIPTION>
%text here
%</DESCRIPTION>
}
\bmumansection{RETURN VALUES}{%<*RETURN>
%text here
%</RETURN>
}
\bmumansection{POSSIBLE ERRORS}{%<*ERRORS>
%text here
%</ERRORS>
}
\bmumansection{SEE ALSO}{%<*SEE>
%text here
%</SEE>
}

\bmumansection is a function that handles creating the MAN like section headers and also handles labels etc.

Now since API function code gets heavily re-used, we had to make our function text re-usable aswell. For this purpose we used the catchfilebetweentags library, which allows us to define tags and then to catch the portion of the file between those tags. (<*NAME> is an example of such a tag).

Now, my problem:

I want to create a contents entry for each of these functions, but without actually showing that section text. The text between the NAME tags beautifully suffices for this kind of stuff. I created my own \include command (called \bmuinclude), which is basically a wrapper for \include : define as such:

\newcommand{\bmuinclude}[1]{
 \phantomsection
 \addcontentsline{toc}{subsection}{ \ExecuteMetaData[functions/#1]{NAME}} 
 label{func:#1}
 \include{functions/#1}
}

\ExecuteMetaData is a function that catches the file specified with functions/#1 and then catches the text between the NAME tag. So my goal would be to get a contents line that says: Application.Connect

however, due to a bug (?) or misuse of the function, what I get is this:

[functions/ApplicationConnect]NAME

It seems the actual command gets ignored and then the text that is supposed to be parameters of that command get read as text, while of course ignoring the curly braces.

So, am I using this function wrong, or is it a bug in that specific function? Most importantly, is there another way of creating contents lines without the text actually showing in the document?

EDIT:

CatchFileBetweenTags.sty Source:

%%
%% This is file `catchfilebetweentags.sty',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% catchfilebetweentags.dtx  (with options: `package')
%% 
%% This is a generated file.
%% 
%% catchfilebetweentags : 2011/02/19 v1.1 - catchfilebetweentags : catch file between delimiters or tags
%% 
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
%% version 1.3 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
%% 
%% This work consists of the main source file catchfilebetweentags.dtx
%% and the derived files
%%    catchfilebetweentags.sty, catchfilebetweentags.pdf, catchfilebetweentags.ins,
%% 
%% catchfilebetweentags : catchfilebetweentags : a new dimen corresponding to the remainder of the line
%% Copyright (C) 2010 by Florent Chervet <florent.chervet@free.fr>
%% 
\NeedsTeXFormat{LaTeX2e}% LaTeX 2.09 can't be used (nor non-LaTeX)
   [2005/12/01]% LaTeX must be 2005/12/01 or younger
\ProvidesPackage{catchfilebetweentags}
         [2011/02/19 v1.1 - Catch file between tags (FC)]
\RequirePackage{etex,etoolbox,ltxcmds}
\RequirePackage{catchfile}
\globtoks\CatchFBT@tok
\newrobustcmd*\CatchFileBetweenDelims[4]{%
   \begingroup
   \edef\CatchFileBetweenDelims{\endgroup
      \noexpand\@testopt
         {\CatchFBT@Work{\noexpand#1}{#2}{#3}{#4}}
         {\noexpand\makeatletter}%
   }\CatchFileBetweenDelims
}% \CatchFileBetweenDelims
\newcommand\CatchFileBetweenTags{}
\begingroup
\@makeother\<%
\@makeother\>%
\@makeother\*%
\catcode`\: 14%
\@makeother\%:
\gdef\CatchFileBetweenTags#1#2#3{:
   \CatchFileBetweenDelims\CatchFBT@tok{#2}{%<*#3>}{%</#3>}[\CatchFBT@sanitize]:
   \CatchFBT@Final{#1}:
}:% \CatchFileBetweenTags
\endgroup
\newrobustcmd*\ExecuteMetaData[2][\jobname]{%
   \CatchFileBetweenTags\CatchFBT@tok{#1}{#2}%
   \global\expandafter\CatchFBT@tok\expandafter{%
            \expandafter}\the\CatchFBT@tok
}% \ExecuteMetaData
\long\protected\def\CatchFBT@Work#1#2#3#4[#5]{%
   \def\CatchFBT@setup{#5%
      \long\def\CatchFile@Do####1#3{\CatchFBT@catchthepart}% discard before start-delim
      \long\edef\CatchFBT@catchthepart####1#4{% capture until end-delim
         \CatchFBT@tok{\endgroup
            \CatchFBT@IsAToken#1
               {\global\noexpand#1{####1}}
               {\xdef\noexpand#1{\noexpand\unexpanded{####1}}}}%
            \noexpand\CatchFBT@discardtherest}%
      \long\expandafter\def
            \expandafter\CatchFBT@discardtherest
                  \expandafter####\expandafter1\CatchFile@EOF{}%
      \everyeof{#3#4}%
      \everyeof\expandafter\expandafter\expandafter{%
         \expandafter\the\expandafter\everyeof\CatchFile@EOF
         \expandafter\the\expandafter\CatchFBT@tok\noexpand}}%
   \CatchFileDef#1{#2}\CatchFBT@setup
}% \CatchFBT@Work
\def\CatchFBT@sanitize{%
   \@sanitize
   \@makeother\{%
   \@makeother\}%
   \endlinechar=`\^^J%
}% \CatchFBT@sanitize
\newrobustcmd*\CatchFBT@Final[1]{\@testopt
   {\CatchFBT@Fin@l{#1}}{}%
}% \CatchFBT@Final
\def\CatchFBT@Fin@l#1[#2]{%
   \begingroup
      \endlinechar\m@ne \makeatletter #2%
      \scantokens\expandafter{%
         \expandafter\CatchFBT@tok\expandafter{\the\CatchFBT@tok}}%
      \CatchFBT@IsAToken{#1}
         {\global#1\expandafter{\the\CatchFBT@tok}}
         {\xdef#1{\the\CatchFBT@tok}}%
      \ifx\CatchFBT@tok#1\else\global\CatchFBT@tok{}\fi
   \endgroup
}% \CatchFBT@Final
\def\CatchFBT@IsAToken#1{%
   \expandafter\expandafter
      \expandafter\CatchFBT@Is@Token
         \expandafter\meaning\expandafter#1\string\toks
            \\\\{first}{second}\\\\%
}% \CatchFBT@IsAToken
\expandafter\def\expandafter\CatchFBT@Is@Token
      \expandafter#\expandafter1\string\toks#2#3\\#4#5#6\\\\{%
      \csname ltx@%
         \if\relax\detokenize{#1}\relax#5%
         \else second\fi oftwo%
      \endcsname
}% \CatchFBT@Is@Token
\endinput
%%
%% End of file `catchfilebetweentags.sty'.

Example of File to be included:

\bmumansection{NAME}{%<*NAME>

Application.Connect

 %</NAME>
}
\bmumansection{SYNOPSIS}{ %<*SYNOPSIS>

Application.Connect(string AuthenticationKey)

 %</NAME>
}
\bmumansection{DESCRIPTION}{%<*DESCRIPTION>

This is a description of the Application.Connect function.

 %</DESCRIPTION>
}
\bmumansection{RETURN VALUES}{%<*RETURN VALUES>

%unimportant text goes here
 %</RETURN VALUES>
}
\bmumansection{POSSIBLE ERRORS}{%<*ERRORS>

%text here
 %</ERRORS>
}
\bmumansection{SEE ALSO}{%<*SEE>

 %unimportant text goes here

 %</SEE>
}​

My 'compile' file (I don't know the exact terms used for latex)

\documentclass[12pt]{article}
\usepackage{bmu}
\setcounter{secnumdepth}{-1} %This hides the number 'header' in the 'mansections'

\bmupreamble{BMU Document}

\begin{document}
\maketitle
\bmuinclude{ApplicationConnect}
\end{document}

And last but not least my bmu.sty package file, which I stripped off all non-related commands

\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{catchfilebetweentags}
\usepackage{verbatim}
\usepackage{hyperref}

%includes a standardized preamble for each document.
%Parameter 1 = title
\newcommand{\bmupreamble}[1]{
    \title{{#1}}
    \author{Me}
    \date{26/01/2012}
}

\newcommand{\bmuref}[1]{
   \hyperref[func:#1]{\ExecuteMetaData[functions/#1]{NAME}}
}

\newcommand{\bmuinclude}[1]{

\phantomsection 
\addcontentsline{toc}{subsection}{ \ExecuteMetaData[functions/#1]{NAME}} 
\label{func:#1}
\include{functions/#1}

}

\newenvironment{indentpar}[1]
{
  \begin{list}{}
  {\setlength{\leftmargin}{#1}}
  \item[]
}
{\end{list}}

% Arguments:
% 1 - section name
% 2 - section indentation
% 3 - section contents
\newcommand{\mansection}[3]
{
  % in case bookmarks are used

  \subsection*{#1}
  \begin{indentpar}{#2}
    #3
  \end{indentpar}
}

\newcommand{\bmumansection}[2]{
    \mansection{#1}{1cm}{#2}
}
​

The functions folder is the folder where I put all the source files for my API function descriptions.

share|improve this question

migrated from stackoverflow.com Jan 21 '12 at 8:19

This question came from our site for professional and enthusiast programmers.

    
From what you say, it seems that one problem is in how \ExecuteMetaData is defined. –  egreg Jan 21 '12 at 9:40
    
Welcome to TeX.sx! Your question was migrated here from Stack Overflow. Please register on this site, too, and make sure that both accounts are associated with each other, otherwise you won't be able to comment on or accept answers or edit your question. –  Werner Jan 21 '12 at 18:40
add comment

1 Answer

A backslash is missing. Correct this line by adding a backslash:

\label{func:#1}

Minimal example with some fictive code and your command bmuinclude, before:

\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage{hyperref}
\newcommand{\ExecuteMetaData}[2][]{<NAME>#1</NAME>}
\newcommand{\bmuinclude}[1]{
 \phantomsection
 \addcontentsline{toc}{subsection}{\ExecuteMetaData[functions/#1]{NAME}} 
 label{func:#1}
 %\include{functions/#1}
}
\begin{document}
\tableofcontents
\section{Test}
\bmuinclude{ApplicationConnect}
\end{document}

It prints:

problematic output

You can see an undesired labelfunc:ApplicationConnect in the text, caused by label{func:#1}, since this would be text. Add a backslash to make \label a command, then the text is not shown.

Regarding \ExecuteMetaData: perhaps add a \protect before this command, to prevent early expansion when it's written into the .toc file:

\addcontentsline{toc}{subsection}{\protect\ExecuteMetaData[functions/#1]{NAME}}
share|improve this answer
    
The missing \ before label was because I messed up formatting the text :) I'll try your suggestions, see what turns up. Thanks! –  Erwin Haasnoot Jan 24 '12 at 13:46
    
Regrettably, I still get the same (bugged) toc line, even after using \protect. [functions/ApplicationConnect]NAME –  Erwin Haasnoot Jan 24 '12 at 13:57
    
@ErwinHaasnoot I suggest to edit the question and to add a compilable minimal example which we could check and fix. Without the code such as the \ExecuteMetaData definition it's hardly possible to see the cause of the error. –  Stefan Kottwitz Jan 24 '12 at 14:06
    
Fair enough, I'll get right on it :) –  Erwin Haasnoot Jan 26 '12 at 10:14
    
I hope this gives you enough information to compile my file. SubSections etc. have been kind of messed up, but it should compile regardless (albeit with errors) –  Erwin Haasnoot Jan 26 '12 at 10:32
add 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.