Insert key words & key phrases into toc

Question

To make the structure of documents (here: my PhD-thesis) comprehensible straight from the ToC, I would like to insert some key words or key phrases in each element of the ToC. I saw this device in a teaching book and I thought it would be a helpful little improvement for longer documents.

My first description of the desired layout lacked of precision, I hope this one is more clear.

Requirements for user-friendlybility: I am looking for a solution that handles key words or key phrases which belong to one part, section etc. in the following way:

a) puts key words/phrases in rows

b) divides them through hyphens

c) one line under the actual part, section etc.

d) key words/phrases without page number

e) depending on the number of key words/phrases it can exceed one line

It should look like this:

Contents

1 section .............................1

key word 1 - key phrase 2 - key word 3

1.1 subsection ...............................5

<p>key word 1 - key phrase 2 - key word 3 -</p>

<p>key word 4 - key phrase 5 - key word 6</p>

Requirement for writer-friendlybility: To make it easier for the writer of the document one command is hoped-for that adapts to a given section, part etc. without any specification within the command in order to prevent him from adjusting the command every time when he is copying it from one sections to a part, subsection, etc.

In the .tex-file it should look like this:

\begin{document}
\section{section} 
bla bla \command{keyword1} few lines or pages of bla bla \command{keyword2} ....

\subsection{subsection} 
bla bla \command{keyword1} few lines or pages of bla bla \command{key phrase2} ....
\end{document}

Does anyone have an idea how to do it?

PS: To convert the keywords in the toc into hyperref-keywords take a look here: Hyperref-ize the keywords in toc. It works with egregs solution.

Answer 1

The tocloft package provides this kind of functionality for chapters: \cftchapterprecistoc; it's not hard to create a similar command for sections. Here's a small example:

\documentclass{report}
\usepackage{tocloft}

% Define a \cftsectionprecistoc
% based on the existing \cftchapterprecistoc
\makeatletter
\newcommand{\cftsectionprecistoc}[1]{\addtocontents{toc}{%
  {\leftskip \cftsecindent\relax
   \advance\leftskip \cftsecnumwidth\relax
   \rightskip \@tocrmarg\relax
   \textit{#1}\protect\par}}}
\makeatother
\begin{document}

\tableofcontents
\chapter{A chapter title}
\cftchapterprecistoc{some keywords}

\section{A section title}
\cftsectionprecistoc{some more keywords}
\subsection{A subsection title}
\end{document}

Answer 2

You can use the \addtocontents and/or the \addcontentsline commands; you can control many aspects of the text to be added:

\documentclass{book}
\usepackage{lipsum}

\begin{document}
\tableofcontents

\addtocontents{toc}{\smallskip\hfil\protect\parbox[t]{.8\textwidth}
{\protect\lipsum[1]}\hfil\par\smallskip}

\chapter{Test chapter}
\lipsum[1]
\addtocontents{toc}{Here we add some text without page number.\par}

\section{Test section}

\lipsum[1-10]

\addcontentsline{toc}{subsection}{Some text formatted like an unnumbered subsection}

\lipsum[1-5]

\subsection{Test subsection}

\addcontentsline{toc}{chapter}{Some text formatted like a chapter and with page number\protect\numberline{}}

\lipsum[1-6]

\section{Another test section}

\end{document}

EDIT: taking into account the new requirements, I defined a new command \AddToToC with two mandatory arguments: the first one indicates the level of the sectional unit (-1 for parts, 0 for chapters, 1 for sections, etc...) and the second one contains the text that will be added to the ToC (the keywords); here's the definition of the command and and example of its use:

\documentclass{book}
\usepackage{ifthen}

\newlength\UnitIndent
\newlength\UnitHangInd

% \AddToToC{<level>}{<text>}
\newcommand\AddToToC[2]{%
  \ifthenelse{\equal{#1}{-1}}
    {\gdef\UnitIndent{2em}\gdef\UnitHangInd{2em}}{}
  \ifthenelse{\equal{#1}{0}}
    {\gdef\UnitIndent{0em}\gdef\UnitHangInd{1.5em}}{}
  \ifthenelse{\equal{#1}{1}}
    {\gdef\UnitIndent{2.3em}\gdef\UnitHangInd{3.8em}}{}
  \ifthenelse{\equal{#1}{2}}
    {\gdef\UnitIndent{5.5em}\gdef\UnitHangInd{7em}}{}
\addtocontents{toc}{\protect\hspace*{\UnitIndent}\hangindent=\UnitHangInd{\itshape#2}\par}
}

\begin{document}
\tableofcontents

\part{Test part}
\AddToToC{-1}{some keywords for the part.}

\chapter{Test chapter one}
\AddToToC{0}{some keywords for the chapter.}

\section{Test section}
\AddToToC{1}{some keywords for the section.}

\subsection{Test subsection}
\AddToToC{2}{some keywords for the subsection.}

\end{document}

The lengths used are those of the book document class; other document classes will require adjusting the lengths. The command doesn't satisfy the last requirement, but all it's required is a simple change to the first argument.

Answer 3

\documentclass[a4paper]{article}
\usepackage{etoolbox}

\makeatletter
\newif\ifsection
\newif\ifsubsection
\newtoks\keywordstoks
\preto\section{\flushkeywords\sectiontrue\subsectionfalse}
\preto\subsection{\flushkeywords\sectionfalse\subsectiontrue}
\preto\enddocument{\flushkeywords}

\newcommand{\flushkeywords}{%
  \ifsection\addtocontents{toc}{\formatkwsection{\protect\@gobble\the\keywordstoks\relax}}\fi
  \ifsubsection\addtocontents{toc}{\formatkwsubsection{\protect\@gobble\the\keywordstoks\relax}}\fi
  \keywordstoks={}}

\newcommand{\keyword}[1]{\@bsphack\keywordstoks=\expandafter{\the\keywordstoks\kwsep#1}\@esphack}
\newrobustcmd{\kwsep}{~-- }
\newrobustcmd{\formatkwsection}[1]{#1\par\medskip}
\newrobustcmd{\formatkwsubsection}[1]{{\leftskip=2.2em\relax#1\par}\smallskip}
\makeatother

\begin{document}

\tableofcontents

\section{Section}

Abc \keyword{key1} def \keyword{key2}

\subsection{Subsection}

Ciao \keyword{key3} ciao \keyword{key4}

\subsection{Another}

x

\end{document}

I'll leave to the OP the task of redefining \formatkwsection and \formatkwsubsection to suit his needs.