Separate Master Doc

Appendix is handled differently in HTML & PDF. For HTML edition, it is just another chapter/part. For PDF, it is a separate directive. More importantly, the Appendix entries get promoted to extra one level. For that I have toc.rst for HTML and latex-contents.rst as the Master Doc

Also, there is a separate Appendix file for HTML and PDF. HTML gets default :toctree: for Appendix, latex get's it with a little tweak.

Here is appendix file for Latex:

%%%%%%%%%%
 Appendix
%%%%%%%%%%

.. include:: acronyms.rst
.. include:: credits.rst
.. include:: testimonials.rst
.. include:: trademark-attribution.rst
.. include:: ../contact.rst

Custom Prolog and Epilog

This is what the conf.py contains:

rst_prolog = "\n.. include:: /%s/include-pre.txt\n\n"%(os.path.abspath('..'),)

rst_epilog = "\n.. include:: /%s/include-post.txt\n\n.. include:: /%s/include-post-conf.txt\n\n"%(os.path.abspath('..'),os.path.abspath('.'))

Interestingly, there are two epilogs, one configuration directory specific, and other configuration specific. Why separate? Figure out yourself.

this is HTML post include:

.. |IDE|                replace:: :abbr:`IDE (Integrated Development Environment)`
.. |JVM|                replace:: :abbr:`JVM (Java Virtual Machine)`

this is latex post include:

.. |IDE|                replace:: :abbr:`IDE`
.. |JVM|                replace:: :abbr:`JVM`

The tag :abbr: is good for HTML. The expansion is shown on Hover. But, in PDF it seems to gets expanded at every instance.

PDF Tweaks

In Sphinx PDF, everything gets a chapter number. That does not seem to be convention, at least with normal printed Books. To make sure that the generated pdf is more-or-less like printed book, I have done following tweaks

The first page of my book is copyrights.rst. (See http://eclipsebook.in/toc/ ) to know the order of pages.

This is how my copyrights.rst looks like

.. raw:: latex

   %%% MEERA-TODO-PDF-PATCH
   %%% From above comment out \tableofcontents

   \setcounter{secnumdepth}{-1}

   %%% MEERA-TODO-PDF-PATCH
   %%% From below comment out \part{Copyrights}

Copyrights
==========

|copy| MMIX-MMX Meera P. Ghumalia.  All rights reserved.

<Some More Contents>
<Some More Contents>
<Some More Contents>

.. raw:: latex

   \tableofcontents

   \renewcommand{\chaptermark}[1]%
   {}{}
   \renewcommand{\sectionmark}[1]%
   {}{}
   \renewcommand{\headrulewidth}{0.5pt}
   \renewcommand{\footrulewidth}{0pt}
   \fancyhf{}
   \fancyfoot[C]{\thepage}
   \fancyhead[RO]{}
   \fancyhead[LE]{}

   %%% MEERA-TODO-PDF-PATCH
   %%% From below comment out \part{preface}
   %%% and \chapter{Dedication}

latex: $(PREREQUISITES)
        $(SPHINXBUILD) -b latex $(LATEXSPHINXOPTS) $(BUILDDIR)/latex
        -@rm $(BUILDDIR)/latex/*.orig
        @echo ===== Patching Start =====
        patch -p0 $(BUILDDIR)/latex/c-cpp-eclipse.tex < book/conf/latex/c-cpp-eclipse.tex.diff
        @echo ===== Patching End =======
        @echo .
        @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
        @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
              "run these through (pdf)latex."

make clean
sphinx-build -b latex -d build/latexdoctrees -c book/conf/latex -D latex_paper_size=a4  book build/latex
cp build/latex/c-cpp-eclipse.tex .

# Edit generated "LayTech" file and follow the Comments.
emacs build/latex/c-cpp-eclipse.tex

diff -U4 c-cpp-eclipse.tex build/latex/c-cpp-eclipse.tex > book/conf/latex/c-cpp-eclipse.tex.diff
rm c-cpp-eclipse.tex