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>
}
%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
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
%%    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
\CatchFileBetweenTags\CatchFBT@tok{#1}{#2}%
\global\expandafter\CatchFBT@tok\expandafter{%
\expandafter}\the\CatchFBT@tok
\long\protected\def\CatchFBT@Work#1#2#3#4[#5]{%
\def\CatchFBT@setup{#5%
\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}}}}%
\long\expandafter\def
\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>
}

%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]{
}

\newcommand{\bmuinclude}[1]{

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

-

## migrated from stackoverflow.comJan 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

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{\bmuinclude}[1]{
\phantomsection
label{func:#1}
%\include{functions/#1}
}
\begin{document}
\tableofcontents
\section{Test}
\bmuinclude{ApplicationConnect}
\end{document}


It prints:

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

-
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