Technical documentation with deeply nested enumerated lists

Question

I'm stuck in a software documentation culture I can't change, and software documentation is expected to have deeply nested sections that look like this:

2.1.5.3.2.1 Some section

This paragraph has some text.

2.1.5.3.2.2 Some other section

This paragraph has more text.

2.1.5.3.3 Higher-level section

Blah, blah, blah.

Anyway, I'd like to use some presentation-independent documentation tool, and the more readable the source, the better. So I'd love it if ReStructuredText could do this, but DocBook or LaTeX would be okay, too.

I just read about how LaTeX has just four levels of nesting counters, and I couldn't get ReStructuredText to count how I wanted at all. After spending lots of time fopping to DocBook documentation, I'm close to opening up Word and struggling with named styles. Any tips?

Answer 1

Latex actually has 7 levels of depth for document structure:

\part{part}     
\chapter{chapter}   
\section{section}    
\subsection{subsection}     
\subsubsection{subsubsection}   
\paragraph{paragraph}   
\subparagraph{subparagraph}

The "4 levels of nesting" is specifically for the use of \enumerate and \itemize, which don't seem to be what you want to use in this case. I think you can probably get what you need using the structure tags from chapter through subparagraph. If you need more than that, you'll be in a world where you have to start doing some deep customization, so that's the point at which I'd abandon LaTeX.

Answer 2

For LaTeX:

in your preamble you'll need:

\setcounter{secnumdepth}{7} %or possibly a greater number if you add to this .sty file
\usepackage{subsections.sty} % or whatever you call the file.

stick all this into a file, i call mine subsections.sty, then put it in the same directory as your .tex document:

\newcounter{subsubsubsection}[subsubsection]
\def\subsubsubsectionmark#1{}
\def\thesubsubsubsection {\thesubsubsection
     .\arabic{subsubsubsection}}
\def\subsubsubsection{\@startsection
     {subsubsubsection}{4}{\z@} {-3.25ex plus -1
     ex minus -.2ex}{1.5ex plus .2ex}{\normalsize\sf}}
% mj02r: original:
%\def\l@subsubsubsection{\@dottedtocline{4}
%     {4.8em}{4.2em}}
% mj02r: for VCE reports:
%\def\l@subsubsubsection{\@dottedtocline{4}
%     {7em}{3.8em}}
% mj02r, 29/12/2004: for thesis:
\def\l@subsubsubsection{\@dottedtocline{4}
     {11.1em}{4.6em}}

\newcounter{subsubsubsubsection}[subsubsubsection]
\def\subsubsubsubsectionmark#1{}
\def\thesubsubsubsubsection {\thesubsubsubsection
     .\arabic{subsubsubsubsection}}
\def\subsubsubsubsection{\@startsection
     {subsubsubsubsection}{5} {\z@} {-3.25ex plus -1
     ex minus -.2ex}{1.5ex plus .2ex}{\normalsize\sf}}
% mj02r: original:
%\def\l@subsubsubsubsection{\@dottedtocline{5}
%     {5.8em}{5.2em}}
% mj02r: for VCE reports:
\def\l@subsubsubsubsection{\@dottedtocline{5}
     {10.7em}{4.5em}}

\newcounter{subsubsubsubsubsection}[subsubsubsubsection]
\def\subsubsubsubsubsectionmark#1{}
\def\thesubsubsubsubsubsection {\thesubsubsubsubsection
     .\arabic{subsubsubsubsubsection}}
\def\subsubsubsubsubsection{\@startsection
     {subsubsubsubsubsection}{6} {\z@} {-3.25ex plus -1
     ex minus -.2ex}{1.5ex plus .2ex}{\normalsize\sf}}
% mj02r: original:
%\def\l@subsubsubsubsubsection{\@dottedtocline{6}
%     {5.8em}{5.2em}}
% mj02r: for VCE reports:
\def\l@subsubsubsubsubsection{\@dottedtocline{6}
     {10.7em}{4.5em}}

\newcounter{subsubsubsubsubsubsection}[subsubsubsubsubsection]
\def\subsubsubsubsubsubsectionmark#1{}
\def\thesubsubsubsubsubsubsection {\thesubsubsubsubsubsection
     .\arabic{subsubsubsubsubsubsection}}
\def\subsubsubsubsubsubsection{\@startsection
     {subsubsubsubsubsubsection}{7} {\z@} {-3.25ex plus -1
     ex minus -.2ex}{1.5ex plus .2ex}{\normalsize\sf}}
% mj02r: original:
%\def\l@subsubsubsubsubsubsection{\@dottedtocline{7}
%     {5.8em}{5.2em}}
% mj02r: for VCE reports:
\def\l@subsubsubsubsubsubsection{\@dottedtocline{7}
     {10.7em}{4.5em}}

Answer 3

In DocBook, a section.autolabel=1 parameter, coupled with a sufficiently-high value for section.autolabel.max.depth will do what you want.

Answer 4

Have you looked at the .. sectnum:: reStructuredText Directive:

.. sectnum::
   :prefix: 2.1.5.3.
   :start: 2

.. contents::

Higher-level section
====================

Some section
------------

This paragraph has some text.

Some other section
------------------

This paragraph has more text.

Other Higher-level section
==========================

Blah, blah, blah.

Note the inability of starting at deeper nested section, then a section following it.

If you want to enumerate all the sections up-to and include the excerpt you gave in the question, .. sectnum:: without any qualifiers will do the trick. reStructuredText limits the level of nested sub sections only by the valid characters that can use to underline (or under- and over-line sections).

See: Automatic Section Numbering

Answer 5

While I can't answer the how-to LaTeX part of the question, I can tell you that Arbortext supports LaTeX natively. You can send the publishing engine or print composer LaTeX and it'll pass it through directly.

It also supports a lot of other composition languages as well and even gives the opportunity to do page-layout manipulation like you'd see in InDesign (without the headache and overhead of ID).

At least you'd get some flexibility to do more, in a more recent technology -- and still do what's required and in use in your business -- at the same time.