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 <[email protected]>
%%
\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.
\ExecuteMetaDatais defined.