Opened 11 years ago

Build the reference manual incrementally — at Version 8

Reported by: Owned by: mpatel tba major sage-5.8 documentation days38 jhpalmieri, leif, niles, hivert, mguaypaq, mhansen Mitesh Patel N/A

Building the Sage reference manual can use significant computer resources. Easing the burden could speed up Sage development.

Experimental.

comment:1 Changed 11 years ago by mpatel

• Authors set to Mitesh Patel
• Cc jhpalmieri added
• Summary changed from Break up the PDF reference manual into smaller pieces to [with patch, needs work] Break up the PDF reference manual into smaller pieces

The attached patch is experimental. Notes:

• sage -docbuild reference pdf fails to build arithgroup.pdf, apparently because of the math macro \ZZ in the title. Unfortunately, I don't know how to fix this.
• Since it replaces the top level PDF file with several smaller files, it breaks the patch at #4460.
• It's not clear what happens to cross-ReST document links. I'll try to investigate.

comment:2 Changed 10 years ago by mpatel

On cross-PDF document links: It seems that Sphinx does not produce these. This may OK, since file:// URLs can break easily.

comment:3 Changed 10 years ago by mpatel

On the \ZZ in arithgroup.tex: It seems the problem stems from \@title in

    \ifsphinxpdfoutput
\begingroup
% This \def is required to deal with multi-line authors; it
% changes \\ to ', ' (comma-space), making it pass muster for
% generating document info in the PDF file.
\def\\{, }
\pdfinfo{
/Author (\@author)
/Title (\@title)
}
\endgroup
\fi


in Sphinx's manual.cls. For some reason, the \math* font commands do not work in this context. I gather that \mathbf is preferred, but one workaround is to use

Arithmetic Subgroups of {\rm SL}_2({\bf Z})


in place of

Arithmetic Subgroups of {\rm SL}_2(\ZZ)


in arithgroup.rst.

Changed 10 years ago by mpatel

Another approach. Depends on #7549. Still experimental. This patch only. sage repo.

comment:4 Changed 10 years ago by mpatel

• Priority changed from minor to major
• Report Upstream set to N/A
• Summary changed from [with patch, needs work] Break up the PDF reference manual into smaller pieces to Build the reference manual incrementally
• Type changed from defect to enhancement

The new patch may make it possible to build and update reference manual chapters semi-independently. I think we can use the intersphinx extension to fix the cross-chapter references. But we'll need to build the manual twice, a la LaTeX.

To build just a chapter, try, e.g.,

sage -docbuild reference/algebras html -juiv3


Still to do:

• Make a combined index page and search page.
• Check that PDF generation works.
• Combine chapter PDF files into one large [optional] PDF file (with pdfjam's pdfjoin)?
• Use a specific LaTeX doc title in each conf.py.
• Fix the "Arithmetic Subgroups" heading on the top-level page.
• Use a visual, 2D layout for the top-level page? Group by general area? Add icons?
• Get a reply from sphinx-dev about making relative paths work.
• Build docs in parallel (cf. #6255) with multiprocessing?
• Replace the "website" PDF link?
• User-friendliness improvements.
• Encourage more compact chapters? It seems that "Combinatorics" takes the most time and memory.
• ...

comment:5 Changed 10 years ago by mpatel

Another important item:

• Use just one _static directory for the manual, not 50+!

comment:6 Changed 10 years ago by mpatel

If this approach is viable, I suggest leaving many (most?) of the "To Do" items for other tickets.

comment:7 Changed 10 years ago by mpatel

While I'm here:

• Copy PDFs from output/latex/ to output/pdf, so that make all-pdf, at least, doesn't do unnecessary work?

comment:8 Changed 10 years ago by mpatel

• Description modified (diff)

Changed 10 years ago by mpatel

PDF fixes. This patch only. sage repo.

Note: See TracTickets for help on using tickets.