Annotated table of contents

Question

To help structuring a large document, I'd like to summarise the key points at the start of a section (or sub(sub)section or chapter) using bullet points and include them in the table of content page. If possible, I would also like to enable/disable the summary (in the section and in the toc). Is there already a package that allows for that or can someone give some ideas for some commands to use?

The final result should look like:

Table of Content
   Introduction..........1
      * some text introducing the topic
      * more text
   Background............5
      * Background section blah, blah
   Chapter 1............10
      * ...
   ...


   Introduction
      * some text introducing the topic
      * more text
      This is the text for the actual introduction. Summary bullet
      points are show because "draft" flag is set.
      More intro text here...

   Background
      ...

   Chapter 1
      ...

I found a similar question being asked here, but when I try to include a itemize environment (e.g. in chapterinfo), I get an error message:

Chapter 1. ) ! Incomplete \iffalse; all text was ignored after line 56. \fi

It would be nice if someone could provide hints for how to make this section-type agnostic (i.e. not using chapterinfo, sectioninfo) and more importantly how to make this an environment, i.e. by using something like:

\section{Introduction}
\begin{summary}
  \item some text introducing the topic
  \item more text
\end{summary}

The fact that the summary doesn't isn't actually also appearing in the text isn't much of a problem for me.

Answer 1

The following might be a starting point. You might tweak the itemize environment to use smaller spaces and stuff.

\documentclass[draft]{report}

\usepackage{enumitem}

\newif\ifSummaryInToC
\newif\ifSummaryInText
\SummaryInToCtrue
\SummaryInTexttrue

\makeatletter
\long\def\grabsummary#1#2\end{%
  \ifSummaryInToC\applysummary{#1}{#2}\fi%
  \ifSummaryInText\applydraftsummary{#2}\fi%
  \end}
\long\def\applysummary#1#2{%
  \addtocontents{toc}{\unexpanded{\unexpanded{%
    \bgroup%
    \let\BEGIN\begin%
    \let\END\end%
    \expandafter\ifcase\numexpr#1+1\relax%
      \vspace*{1ex}% part needs more distance in ToC than the others
    \else%
      \vspace*{-1ex}%
    \fi%
    \expandafter\ifcase\numexpr#1+1\relax%
      \@tempdima=1em\relax% indentation for part-level
    \or%
      \@tempdima=2.3em\relax% indentation for chapter-level
    \or%
      \@tempdima=3.8em\relax% indentation for section-level
    \or%
      \@tempdima=7em\relax% indentation for subsection-level
    \or%
      \@tempdima=11.1em\relax% indentation for subsubsection-level
    \else%
      \@tempdima=1.7em\relax% fallback indentation
    \fi%
    \begin{itemize}[leftmargin=\@tempdima]%
      \baselineskip=0.5\baselineskip% crude way of changing the space
      \parskip=0pt% crude way of changing the space between items
      \parsep=0pt% crude way of changing the space between items
      \itemsep=2pt% crude way of changing the space between items
        #2%
    \end{itemize}%
    \egroup%
  }}}}
\long\def\applydraftsummary#1{%
  \hrule width \textwidth\kern4pt%
  \textbf{Summary}%
  \begin{itemize}#1\end{itemize}%
  \hrule width \textwidth\medskip}%
\newenvironment{summary}[1][0]{\let\BEGIN\begin\let\END\end\grabsummary{#1}}{}%
\makeatother

\begin{document}
\tableofcontents
\part{FOO} % summary is not on the same page as heading
\begin{summary}[-1]
  \item foo
  \item bar
\end{summary}
\chapter{Foo}
\begin{summary}
    \item foo
    \item bar
    \item baz
    \item very long bullet point that describes very much and eventually needs a
      line break
    \BEGIN{itemize}
      \item test
    \END{itemize}
    \item foo
\end{summary}
This is the text for the actual Foo.
Summary bullet points are shown because \verb|\SummaryInTexttrue| is set.
If \verb|\SummaryInToCtrue| is also set, these bullet points show up in the ToC,
too!
\section{Foobar}
\begin{summary}[1]
  \item Foo
    \BEGIN{itemize}
      \item foo
      \item bar
    \END{itemize}
  \item Bar
\end{summary}
\subsection{foobar}
\begin{summary}[2]
  \item Foo
    \BEGIN{itemize}
      \item foo
      \item bar
    \END{itemize}
  \item Bar
\end{summary}
\chapter{Bar}
\begin{summary}
    \item foo
    \item bar
    \item baz
\end{summary}
\section{Foobaz}
\end{document}

EDIT: I changed the answer to cope everything you asked for (I think). If something is missing, feel free to ask.

You should not nest an environment in the summary environment, because \grabsummary scans for \end and if it encounters a \end stops. I've made another edit, which allows the use of nested environments with \BEGIN and \END (technically the \BEGIN part isn't necessary, but I think it looks better if they match). Note that the definitions of \BEGIN and \END are only valid inside the summary-environment.

You can manually alter the indentation by giving the level as an optional argument to summary with the following meanings:

-1: part

0: chapter

1: section

2: subsection

3: subsubsection

Default is 0 resulting in chapter level of indentation.

Results if both \ifSummaryInToC and \ifSummaryInText are true: