How to define parallel section-like headings?

Question

I am trying to help typeset a book for a friend, and I've converted most to use chapters, sections, subsections and subsubsections. However, some sections are of the form "Digression N: Text". The digression numbering increments independently, and I've managed to define my own style of heading. Here's my LaTeX so far:

\documentclass{article}
\usepackage{hyperref}

\newcounter{dig}
\newcommand{\digname}{digression}
\newcommand{\digautorefname}{Digression} % Found first by hyperref \autoref{...}
\makeatletter
% http://infohost.nmt.edu/tcc/help/pubs/nmtthesis/old/annotated/at.startsection.html
% http://help-csli.stanford.edu/tex/latex-sections.shtml
% http://zoonek.free.fr/LaTeX/LaTeX_samples_section/0.html
\newcommand\dig{\@startsection {dig}{2}{\z@}%
                               {-3.5ex plus -1ex minus -.2ex}%
                               {2.3ex plus .2ex}%
                               {\normalfont\Large\bfseries}}
\makeatother

\newcommand{\digprefix}{\digname\ \thedig :\ }
\newcommand{\digression}[1]{%
    \phantomsection%
    \refstepcounter{dig}%
    \addcontentsline{toc}{dig}{\digprefix #1}%
    \dig*{\digprefix #1}
}


\begin{document}
\tableofcontents

\section{You're Number One}
If you're interested, see \autoref{di:putfirst}.

\digression{Putting You First}
\label{di:putfirst}
Yes, but see \autoref{di:look}.

\dig{Strangely Echoed}
\label{di:echo}
This is body text.

\digression{Look Over There!}
\label{di:look}
What is happening in \autoref{di:echo}? The dig counter is currently \thedig . Go back to \autoref{di:putfirst}.

%\section{What's Best}
Choose the good.

\subsection{Huh}
I missed it.

\end{document}

It's a few lines, but there are some problems. I'm processing it with two calls to pdflatex dig.tex. Here's the story:

1. If I put a section after the digressions, pdflatex won't process the second run because it snags in the dig.toc file. It complains that "Something's wrong--perhaps a missing \item" at ...}{\numberline {2}What's Best}{1}{Section.2}.
2. The call to \dig{Strangely Echoed} confusingly also puts the digression title after the heading (but integrates nicely with \autoref{...}).
3. In an attempt to rearrange the digression heading text and remove the duplicate, I defined \digression, but I can't make it integrate with the \autoref feature of the hyperref package. In the output PDF, \autorefs that reference a \digression use the "section" prefix.
4. The table of contents doesn't seem to format nicely for \dig based headings either.

So, please, how can I get a separately numbered sequence of Digression headings of the form "Digression N: Title" that can intersperse between calls to \section and work with \autoref?

Answer 1

1. You need to provide a definition for \l@dig, which is what LaTeX translates a call of \contentsline{dig}

2. You need to define a macro \digmark (there are \sectionmark and all the other similar ones)

3. It's best to avoid *-versions if you want to cooperate with \autoref

4. See 1.

I'd do in this way:

\documentclass{article}

\newcounter{digression}
\newcommand{\digressionname}{Digression}
\newcommand{\digautorefname}{Digression} % Found first by hyperref \autoref{...}
\makeatletter
\newcommand\digression{\@startsection{digression}{2}{\z@}%
                               {-3.5ex plus -1ex minus -.2ex}%
                               {2.3ex plus .2ex}%
                               {\normalfont\Large\bfseries}}
\renewcommand*{\@seccntformat}[1]{%
  \@nameuse{additional@#1}\@nameuse{the#1}\quad}
\def\additional@digression{\digressionname\space}
\newcommand*\l@digression[2]{%
  \ifnum \c@tocdepth >\z@
    \addpenalty\@secpenalty
    \addvspace{1.0em \@plus\p@}%
    \setlength\@tempdima{1.5em}%
    \begingroup
      \renewcommand\numberline[1]{Digression ##1: }%
      \parindent \z@ \rightskip \@pnumwidth
      \parfillskip -\@pnumwidth
      \leavevmode \bfseries
      \advance\leftskip\@tempdima
      \hskip -\leftskip
      #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
    \endgroup
  \fi}
\def\digressionmark#1{}
\makeatother

\begin{document}
\tableofcontents

\section{You're Number One}
If you're interested, see \autoref{di:putfirst}.

\newpage\digression{Putting You First}
\label{di:putfirst}
Yes, but see \autoref{di:look}.

\newpage\digression{Strangely Echoed}
\label{di:echo}
This is body text.

\newpage\digression{Look Over There!}
\label{di:look}
What is happening in \autoref{di:echo}? The dig counter is currently \thedigression . Go back to \autoref{di:putfirst}.

\newpage\section{What's Best}
Choose the good.

\subsection{Huh}
I missed it.

\end{document}

The typesetting of "digression" entries in the ToC are similar to sections; change the definition of \l@digression.

The trick of redefining \@seccntformat allows for adding "Digression" in front of the number.

I don't know how to set a bookmark level for digressions, sorry.