# Creating independently-numbered Chapter-level structures

I'm writing a book in which, between chapters, I may have chapter-size chunks of text that discuss a software package related to the book's content. Consequently, I wish to label these things something other than chapters. For example, I'd like my TOC to be something like this:

1   Here would go my title for Chapter 1

2   Here would go my title for Chapter 2

Software Break 1: Getting to Know Foo and Bar

3   Here would go my title for Chapter 3

Software Break 2: Here Come Baz and Quux!

4   Here would go my title for Chapter 4

and so on. You can see three requirements here:

1. Software Breaks have a counter independent from that of Chapters.
2. Software Breaks appear differently in the TOC.
3. Otherwise, Software Breaks function identically to chapters. E.g., somewhere in a chapter, I might type something like this:

We covered widget frozzling in Software Break \ref{break:intro} on page \pageref{break:intro}.


I guess what I'm saying is that I want to recreate whatever the standard book document class does for Chapters, but again, as a totally other class of thing, called a Software Break. So I took a look at the book.cls source code (here), but I'm simply not a sophisticated enough LaTeXer to understand it yet. I could try copying and pasting big chunks of stuff about chapter definitions, but I'd have no confidence I was doing it right or that it would succeed.

Alternately, perhaps what I need to do is manually change the name/appearance/number of just some of my chapters? I won't exactly be moving chapters around a lot, so if I have to manually number them, it's not a big deal.

-
You will need quite an infrastructure if you want to duplicate the full functionality of \chapter. Do you need sections and subsections inside a Software Break? What about figure, table, listings, etc. numbering? You cannot have two Figs 1.2 for example or Fig 3.5 inside Software Break 1, that will be very confusing. If you are not using \part then I would recommend that you number your software breaks with Roman Numerals I, II, III, ... What about hyperref support? – Danie Els Feb 14 '13 at 5:09

Here's how I ended up solving my own problem.

Overall gist:

1. Create another counter for software break sections.
2. Create a new command for starting software break sections, which swaps the chapter counter for the software break counter, reformats chapter headings and numbering and appearance in the ToC and everything.
3. Create a separate command for when a software break is ending, to put everything back to normal.

The code looks like this, and requires \usepackage{titlesec}.

% Define and initialize counters used below
\newcounter{swbreak}
\setcounter{swbreak}{0}
\newcounter{swapspace}

% Choose the phrase that will be used in the titles:
\def\swbreakphrase{Software Break}

% The following one-parameter environment is used to wrap a "software break."
% Yes, that's write, you wrap the entire chapter-like thing in this:
% \begin{swbreak}
% ...lots and lots of stuff...
% \end{swbreak}
\newenvironment{swbreak}[1]{
% Swap chapter and software break counters:
\setcounter{swapspace}{\value{chapter}}
\setcounter{chapter}{\value{swbreak}}
% Use A,B,C for software breaks instead of 1,2,3:
\renewcommand{\thechapter}{\Alph{chapter}}
% Don't let the actual chapter title *also* show up in the ToC:
% Change Chapter heading to Software Break heading, and start a new "chapter":
\titleformat{\chapter}[display]{\normalfont\huge\bfseries}{Software Break \thechapter}{20pt}{\Huge}
\chapter{#1}
% Re-enable chapter heading style, and chapters appearing in ToC:
\titleformat{\chapter}[display]{\normalfont\huge\bfseries}{\chaptertitlename\ \thechapter}{20pt}{\Huge}
% Insert a custom ToC entry style for this software break:
}{
% Swap chapter and software break counters back to the way they were:
\setcounter{swbreak}{\value{chapter}}
\setcounter{chapter}{\value{swapspace}}
% Use 1,2,3 again instead of A,B,C:
\renewcommand{\thechapter}{\arabic{chapter}}
}

-
Although this solution fits my needs, those with appendices may have problems with it. See Danie Els' answer below for a more comprehensive solution. I chose this one for brevity/simplicity, but your needs may not be as simple as mine. – Nathan Feb 18 '13 at 16:33

Here is an example that defines an environment for Software Breaks and corrects the TOC

\documentclass{book}
\makeatletter

\newcommand\SWbreakname{Software Break}

%-- Counter
\newcounter{SWbreak}
\renewcommand\theSWbreak{\Alph{SWbreak}}

%-- Software break environment
%-- Usage: \begin{SoftwareBreak}[<short title>]{<full title>}
%--           Contents....
%--        \end{SoftwareBreak}
%--
\newenvironment{SoftwareBreak}[2][\SB@temp]
{\gdef\SB@temp{#2}%
\global\let\@chapapp@old=\@chapapp
\global\let\thechapter@old=\thechapter
\gdef\@chapapp{\SWbreakname}
\gdef\thechapter{\theSWbreak}%
\SB@chapt{#1}{#2}%
}%
{%
\global\let\@chapapp=\@chapapp@old
\global\let\thechapter=\thechapter@old}

%-- Custom chapter to correct TOC
\newcommand\SB@chapt[2]{%
\if@openright\cleardoublepage\else\clearpage\fi
\thispagestyle{plain}%
\global\@topnum\z@
\@afterindentfalse
\ifnum \c@secnumdepth >\m@ne
\if@mainmatter
\refstepcounter{SWbreak}%
{\protect\numberline{\SWbreakname~\theSWbreak:}#1}%
\else
\fi
\else
\fi
\chaptermark{#1}%
\if@twocolumn
\else
\fi}

%-- TOC formating
\newcommand*\l@SWbreak[2]{%
\ifnum \c@tocdepth >\m@ne
\vskip 1.0em \@plus\p@
\settowidth\@tempdima{\bfseries \SWbreakname~XX:~}%
\begingroup
\parindent \z@ \rightskip \@pnumwidth
\parfillskip -\@pnumwidth
\leavevmode \bfseries
\hskip -\leftskip
#1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
\penalty\@highpenalty
\endgroup
\fi}

%-- Keep hyperref happy
\def\toclevel@SWbreak{0}

\makeatother

\usepackage{lipsum}
\begin{document}
\frontmatter
\tableofcontents
\listoffigures

\mainmatter
\chapter{First Chapter}
\section{A section}
\lipsum[1]
\section{Another section}
\lipsum[1]
\begin{figure}
\caption{A figure}
\end{figure}
\lipsum[1]

\begin{SoftwareBreak}[First Software Break]
{First Software Break plus a very long line to check for wrapping}
\section{A section in a Software Break}
\lipsum[1]
\section{Another section in a Software Break}
\lipsum[1]
\begin{figure}
\caption{A figure}
\end{figure}
\lipsum[1]
\end{SoftwareBreak}

\chapter{Second Chapter}
\section{A section}
\lipsum[1]
\section{Another section}
\lipsum[1]
\begin{figure}
\caption{A figure}
\end{figure}
\lipsum[1]

\begin{SoftwareBreak}{Second Software Break}
\section{A section in a Software Break}
\lipsum[1]
\section{Another section in a Software Break}
\lipsum[1]
\begin{figure}
\caption{A figure}
\end{figure}
\lipsum[1]
\end{SoftwareBreak}

\end{document}

-
Danie, Thanks very much for this contribution! It's definitely more sophisticated than what I did. In particular, it's clear to me that I should use a \newenvironment rather than two \newcommands. Are there other particular functional advantages to your way over mine? I think I'm not savvy enough on all the ingredients of yours to judge accurately. Thanks! – Nathan Feb 15 '13 at 13:32
I took some of your ideas and used them to improve my original answer, and now I'm voting for that one just because it's shorter and simpler. But this may be more complete and I'm glad it's here in case anyone else needs it. Thank you! – Nathan Feb 18 '13 at 5:06
@Nathan: You need the optional argument for the short chapter that is passed on to the running heads and TOC. The hard coding \renewcommand{\thechapter}{\arabic{chapter}} during the reset limits you option and will cause havoc if you are using appendixes. If you want proper indents in your TOC you will need the same code I'm using. – Danie Els Feb 18 '13 at 6:37
Ah yes, I see you're right. Unless one numbers Appendices with something like I,II,III, then there will be conflict of section/figure/etc. numbers. Good point. Since I have only one appendix, and my TOC indentation looks good now, I plan to stick with my solution, but I'm glad you clarified that for the next person that comes by here. I'll add a comment on my solution that a more comprehensive one is below for those that need the extra benefits it provides. Thanks! – Nathan Feb 18 '13 at 16:33