errors building latex PDF documentation

[prjemian]

Recent builds with the jenkins build server report an error while building the PDF version of the manual.

This is confirmed reproducible when building the PDF version of the manual from the Linux command line. (Note the default Makefile rules only build the HTML version.)

The root cause is not yet known. Here is the error message (from nexus.log):

! LaTeX Error: Too deeply nested.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.21441 \begin{quote}
                     
? 
! Emergency stop.
 ...                                              

The point of the error is in documentation of the NXmx definition.

[prjemian]

The LaTeX error log is not helpful in resolving the root cause. Attempting to diagnose by removing major sections in NXmx as a test (removed everything within the NXentry group), the same error occurred but was shifted into NXcanSAS.

Also upgraded my local Sphinx to latest release, 1.5.4, but that did not change the error.

Still puzzled. Seems that the online HTML docs continue to be updated, thus this issue has less impact.

[prjemian]

449b403 is related

[prjemian]

using Sphinx 1.6.2 on local workstation, build problem still remains

Also, there is a problem on current travis-ci builds where the latexmk command is not found.

[prjemian]

• looks like some consequence of refactor anyUnitsAttr #555

• diagnosing, make latexpdf always fails on a /begin{quote} line (many such lines in nexus.tex though)

• iteratively removing (temporary only) NXDL files that cause the build to fail, looking for a common factor

  • applications/NXmx.nxdl.xml.0
  • applications/NXsas.nxdl.xml.0
  • applications/NXsastof.nxdl.xml.0
  • contributed_definitions/NXsnsevent.nxdl.xml.0
  • contributed_definitions/NXsnshisto.nxdl.xml.0

in NXsas, this .tex code:

\begin{quote}

Any of these values: \sphinxcode{nxcylinder} \textbar{} \sphinxcode{nxbox}
\end{quote}

which is from this .rst intermediate source:

            **shape**: (required) :ref:`NX_CHAR <NX_CHAR>`


              Any of these values: ``nxcylinder`` | ``nxbox``

which is from this NXDL.xml source

            <field name="shape" type="NX_CHAR">
              <enumeration>
                <item value="nxcylinder"/>
                <item value="nxbox"/>
              </enumeration>
            </field>

Similarly for NXmx, this XML source triggers the problem:

	<attribute name="transformation_type">
		<enumeration>
			<item value="translation" />
		</enumeration>
	</attribute>

Will look at the Python code that converts the enumeration element in NXDL files into rST code.

[prjemian]

The specific error from latex is always (with different line number for different NXDL file encountered):

! LaTeX Error: Too deeply nested.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.22308 \begin{quote}
                     

[prjemian]

might be related: sphinx-doc/sphinx#777

[prjemian]

summary: fixes for this range from reduce nested levels to modify sphinx style files

We'll try to reduce the nested levels first.

[prjemian]

related search: https://duckduckgo.com/?q=latex%3A+quote+environment+too+deeply+nested&t=lm&ia=qa

[prjemian]

from the Sphinx manual, there is no specific comment for rST definition lists but the general admonition applies:

... keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.

and that is the root problem why the PDF can't be built now. Need to re-design the page layout for describing NXDL files.

[prjemian]

There's a new key that was added (sphinx-doc/sphinx#777) to Sphinx with v1.5 (current is 1.6.3) specifically to handle this situation.

http://www.sphinx-doc.org/en/stable/config.html?highlight=maxlistdepth

[prjemian]

77e7133 fixed this but only if sphinx is upgraded to 1.5 or later (current release 1.6.2, jenkins has 1.4.8 so can't handle this yet)

[prjemian]

@FreddieAkeroyd Can you please update sphinx on the nexus build server?