# Adding to section names based on their contents

I've got a document that talks about requirements fulfilled. Each requirement has an official name, and so I've made macros that consume a requirement name and make marginpars and index entries with the name, and write it in aux files so I can make spreadsheets and stuff. So here's an example:

\section{Offensive capabilities}
\implements{KEPO-1} The spud cannon is capable of imparting 3209 ft-lb
of kinetic energy to its projectile, raising an average potato to the
required maximum of 300 feet.

\implements{FEXT-1} A fire extinguisher is kept near the spud cannon
and checked hourly.

\section{Defensive capabilities}
\implements{POFT-1} Shingles and roof substructure are provided which
are capable of withstanding 300 potato strikes.

\implements{POFT-1} Non-stick coatings are applied to resist slime
attacks.


My question is this: how can I change the section names according to what's inside each section, so that my table of contents can look something like this?

1.1 Offensive capabilities (KEPO-1, FEXT-1) ..... 5
1.2 Defensive capabilities (POFT-1) ............. 6


--

% \def alphFOO macros: chapter, section, etc; see below for details
\let\old@sect\@sect
\def\@sect#1#2#3#4#5#6[#7]#8{%
% #1 is something like section or subsection; #2 is depth in
% hierarchy (1 = chapter, 2 = section, etc); mumble; #7 is section
% title for use in TOC (usually same as #8); #8 is section title
% for use in document body
\ifnum #2>\c@tocdepth
% section will not show in toc. do the usual thing
\old@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{#8}
\else
% make unique name for section, e.g. paragraphptchseIsussIIp
\edef\last@division{#1\csname alph#1\endcsname}
% make unique name for macro to contain title of section
\edef\last@divtitle{\csname titleof\last@division \endcsname}
% define title macro initially
\expandafter\def\last@divtitle{#7}
% replace title written in toc file with reference to title macro
\old@sect{#1}{#2}{#3}{#4}{#5}{#6}[\noexpand%
\csname titleof\last@division\endcsname]{#8}
\fi}
\expandafter\edef\last@divtitle{\last@divtitle ---#1}}
\newcommand{\implements}[1]{%


That seemed like a good idea---section titles in the table of contents were added on to---but it borked the titles in the PDF bookmarks ("2.3 titleofsectionptchse1su2"), and the TOC got too repetitive when I chanced to mention a requirement more than once (Bla---POFT-1---POFT-1---POFT-1).

I started to try to write another aux file like so:

division:section:Offensive capabilities
division:section:Defensive capabilities


and postprocess it into a replacement toc file with a Python script, but there are two problems there: (1) this is a multifile document, and the processor needs to go through the included and inputted files in the same order TeX would, which is tedious and error-prone to duplicate; (2) this process changes the length of the toc, possibly pushing sections onto different pages, but the page numbers are written in the toc. So LaTeX needs to change the toc after the script, but then the script needs to change the toc again. Ew.

--

A complete document:

\documentclass{article}
\newcommand \alphpart {pt\Roman{part}}
\ifx\chapter\undefined
\newcommand \alphsection {\alphpart se\Roman{section}}
\else
\newcommand \alphchapter {\alphpart ch\Roman{chapter}}
\newcommand \alphsection {\alphchapter se\Roman{section}}
\fi
\newcommand \alphsubsection {\alphsection su\Roman{subsection}}
\newcommand \alphsubsubsection {\alphsubsection ss\Roman{subsection}}
\newcommand \alphparagraph {\alphsubsubsection p\Roman{paragraph}}
\newcommand \alphsubparagraph {\alphparagraph sp\Roman{subparagraph}}
\makeatletter
% paste "Here's what I've tried already" here
\makeatother
\begin{document}
\tableofcontents
% paste "So here's an example" here
\end{document}


Call that main.tex. Build this way:

pdflatex main.tex
pdflatex main.tex


View the PDF. Observe that the TOC looks OK in the paper. Now look at the PDF bookmarks and see that their names are wrong

-
Must the additions appear only in the ToC or do you want them to appear also in the headers and in the section titles in the document? – Gonzalo Medina Sep 28 '11 at 19:19
I'd like to show them only in the ToC: my actual implementation already shows them in a marginpar, so once you arrive at a section it should be easy to pick out the paragraph talking about the requirement you're looking for. Then again, these additions weren't my idea in the first place; the people requiring the additions could say, "That's really nice; but can you write them in the body of the document too?" – jared Sep 28 '11 at 20:11

Here's something that works but is not nearly general enough.

I cracked open the hyperref package and found that the \addcontentsline macro is what adds the PDF bookmark. Its third argument, the section's "tag" as hyperref's comments call it, is usually of the form \numberline{\thesection}Section name. With my changes described above, that third argument looks like \numberline{\thesection}\titleofsectionptchseII. So I made a copy of the definition of \addcontentsline and replaced this part of it:

\Hy@writebookmark{\csname the#2\endcsname}%
{#3}%
{\@currentHref}%
{\Hy@toclevel}%
{#1}%


with this:

\edef\Hy@expandedtag{#3}
\Hy@writebookmark{\csname the#2\endcsname}%
{\Hy@expandedtag}%
{\@currentHref}
{\Hy@toclevel}%
{#1}%


So now the \titleofsectionptchseII is expanded. But so is everything inside it. That's bad, because I can no longer say \section{Foo {\tt bar} baz}, or \section{Foo \label{foo}}: the expansions of these macros into TeX primitives are not permissible PDFDocStrings.

If I were better at figuring out expansion, I could expand the argument of \addcontentsline only once or twice, expanding the \titleoffoo macro but not the macros inside its value. Sort of like this or this, except I don't entirely understand those.

-