Generating stuff that comes before the table of contents, or "front
matter", is pretty difficult right now. Lacking a way to do it natively
through Sphinx, and not wanting to have duplicate versions of the same content
in rST and TeX to get out of sync, I resorted to modifying the generated TeX
file before building a PDF from it.
Our first rST file in the index is intro.rst. In it, we have some copyright
information which we wanted to appear inside the front cover, before the TOC.
Original order:
TOC (generated)
Copyrights
Welcome
Typographic Conventions
Introduction
New order:
Copyrights
TOC (generated)
Welcome
Typographic Conventions
Introduction
It turned out that moving the TOC left the old "Contents" strings showing in
the footer on non-TOC pages, so code to create a new page style called
"frontmatter" to hide those strings was added to the preamble:
% a plain page style for front matter
\fancypagestyle{frontmatter}{%
\fancyhf{}
\fancyhf[FCO,FCE]{}
\fancyhf[FLE,FRO]{\textbf{\thepage}}
\fancyhf[FLO,FRE]{}
}
In intro.rst after the copyrights section, a raw:: directive adds a marker
string (--TABLEOFCONTENTS--) to the TeX file where the TOC is actually desired
to appear.
The pagestyle is set to the new frontmatter style immediately after that to
prevent "Contents" from being shown in the footer where the TOC had been. This
is not technically front matter, since it will be after the new location of the
TOC, but close enough.
A new, unnumbered section header is manually added, and that section is added
to the TOC:
.. raw:: latex
\par--TABLEOFCONTENTS--\par
\pagestyle{frontmatter}
\section*{Welcome}\addcontentsline{toc}{section}{Welcome}
The "Welcome" text comes immediately afterwards in intro.rst.
Before the existing Typographic Conventions section, a page break and another
section header are inserted with the raw:: directive:
.. raw:: latex
\pagebreak
\section*{Typographic Conventions}
\addcontentsline{toc}{section}{Typographic Conventions}
At the end of the typography text in the intro.rst file, the page style is
again set to "frontmatter". This must be done here because of the order of
rendering TeX uses. (Apparently. "It's stuck in there with glue or something,
I don't know.")
.. raw:: latex
\pagestyle{frontmatter}
One more change is needed. The generated TeX file still has the old
\tableofcontents in the original place. So we use sed to delete that and
replace the marker string with it. This is particularly crude and ugly, and I
will happily rip it out when there is a way to do this natively in Sphinx. We
run sed from the Makefile:
...
@echo "Running LaTeX files through pdflatex..."
# move the table of contents to a different spot
@sed -i '' -e '/\\tableofcontents/d' $(BUILDDIR)/latex/*.tex
@sed -i '' -e 's/\\par--TABLEOFCONTENTS--\\par/\\tableofcontents/'
$(BUILDDIR)/latex/*.tex
# gmake is required here
gmake -C $(PREPROCDIR)/$(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF file is" $(BUILDDIR)/latex/*.pdf
Notes:
1. Document repo with source:
https://github.com/freenas/freenas-docs/
2. Our docs use a preprocessor, and that is not shown here to keep it
brief. See #1 for the full thing.
3. We generate these PDFs on FreeBSD, which uses bmake natively. Some of
the LaTeX PDF Makefile is gmake-specific, so it is used in the last
step.
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
