Multipub: Managing a LaTeX Manuscript for Concurrent Print and Electronic Formats

To enable multi-target compilation, include²²I couldn’t package multipub as a style file because LaTeXML only accepts style files for which it has bindings. the multipub package right after the documentclass declaration in your master document and specify your compilation target immediately below; then, just before \begin{document}, invoke the \mutipubbegin macro like so:

\documentclass[...]{...}
\input{multipub}
\multipub{HTML}
...
...
\multipubbegin
\begin{document}
...
	

All target names can be used to define conditional portions of the LaTeX manuscript that will be active only when the target is selected; for instance

\begin{PRINT}
  % custom page formats for the PRINT version
  \include{styles/printlayout}
  \usepackage[utopia]{mathdesign}
  \usepackage{pstricks}
\end{PRINT}

\begin{EPUB}
  % custom page formats for the EPUB version
  \include{styles/epublayout}
\end{EPUB}
	

Since we’ll be using LaTeXML, the first step in preparing a manuscript for electronic publishing is to make sure that all critical packages have available LaTeXML bindings (see Figure 1). A critical package is a functional package that will be needed for all compilation targets. Please note that any package affecting the page layout only (e.g. specific font packages) will be irrelevant when compiling for HTML or EPUB and so it can be conditionally included for PRINT or KINDLE as explained above. Another exception is the inclusion of PSTricks-derived packages, for which a different strategy is provided below.

With multi-part documents (such as the chapters in a book or different sections in a longer text) it is often convenient to have a master document and include the relevant files from subfolders; e.g. if you have a book.tex master file in the top-level directory and a series of subfolders containing chapters you may find yourself writing something like:

\documentclass[...]{book}
...

\begin{document}

\title{My Book}
\maketitle

\include{ch01/chapter1.tex}
\include{ch02/chapter2.tex}

\end{document}
	

The rationale behind this file structure is to organize the material for each chapter in separate subfolders, possibly creating another level of folders in each subfolder to collect figures or data files. The problem, however, is that if you now, say, include a figure in a chapter file using a path relative to the chapter’s subfolder, the figure will not be found since LaTeX assumes that all paths are relative to the master document. To work around this problem without using absolute paths, multipub defines two specific macros. In your master document, use the \includefile macro to include chapters, separating the path from the file name:

\documentclass[...]{book}
...
\includefile{ch01}{chapter1.tex}
\includefile{ch02}{chapter2.tex}
	

then, in each included file, you can use the \localpath macro to include files relative to the included file itself. For example, assume the folder ch01/figs/ exists; then in chapter1.tex you can use things like:

\includegraphics{\localpath{figs/fig.eps}}
	

and the document will compile. Using the \includefile macro is critical with respect to PSTricks figures, as explained in the following section.

As a final note, do NOT use underscores in the filenames or path names as this seems to confuse LaTeXML.

LaTeXML supports picture inclusion via \includegraphics; in other words, figures defined as in the code snippet below should present no problem across compilation targets:

\begin{figure}
  \includegraphics{figs/figure.eps}
\end{figure}
	

On the other hand, although LaTeXML has some basic PSTricks bindings, it certainly does not cover the multitude of useful PSTricks-based packages in use today. Therefore the strategy for multitarget compilation is the following:

• •

  in the main document folder (or in each chapter folder) create a subfolder called ps

• •

  isolate the PSTricks-specific code for each figure in the tex file and save it in separate small file in the ps folder (e.g. ps/fig3.tex)

• •

  use the \pstf macro to include the PsTricks figure using the file name without extension

When compiling for the EPUB target, the mpbuild compilation script will pre-render all the figures in all the ps subfolders of your manuscript.

For example, consider the following figure:

obtained with the following code:

\begin{figure}
  \center
  %%%% BEGIN PSTricks %%%
  \savedata{\smooth}[
    1.0000 1.0000 1.1579 1.0011 1.3158 1.0130 1.4737 1.0484
    1.6316 1.1201 1.7895 1.2408 1.9474 1.4232 2.1053 1.6777
    2.2632 1.9852 2.4211 2.3076 2.5789 2.6068 2.7368 2.8445
    2.8947 2.9824 3.0526 2.9828 3.2105 2.8418 3.3684 2.6079
    3.5263 2.3338 3.6842 2.0725 3.8421 1.8769 4.0000 1.8000]
  \psset{xunit=1.8cm,yunit=0.8cm,linewidth=0.8pt}
  \begin{pspicture}(-.5,-.5)(5.5,3.5)
    \pscustom{
      \dataplot[plotstyle=curve,linewidth=1.1pt]{\smooth}
      \gsave
      \psline(4,0) \psline(1,0)
      \fill[fillstyle=solid,fillcolor=lightgray]
      \grestore}
    \psline{->}(0,-.1)(0,3.4)
    \psline{->}(-.1,0)(5.4,0)
    \rput[t](1,-.1){$T_0$}
    \rput[t](4,-.1){$T_1$}
    \psline[linestyle=dashed]{-}(0.5,1.983)(4.5,1.983)
  \end{pspicture}
  %% END PSTricks %%%%
\end{figure}
  

Cut all the lines between the BEGIN PSTricks and END PSTricks markers and save them as the file ps/fig1.tex. Now you can include the figure with

\begin{figure}
  \pstf{fig1}
\end{figure}
	

When compiling for the PRINT target, the macro will include the pre-rendered version of the figure if it is available, otherwise it will include the PSTricks code directly (obviously in this case the PRINT version must include all necessary PSTricks packages; you can do that within the conditional inclusion section in the preamble of the document). When compiling for EPUB the pre-rendered figures must be available and a compilation error is raised otherwise.

Normally, the size of the figures is automatically adjusted to the compilation target; however, the \pstf macro takes an optional argument that can be used to specify the width of the included pre-rendered figures.

	> mpbuild PRINT mybook
	

Compilation in this case is a simple LaTeX$\to$ dvips $\to$ ps2pdf sequence and it will generate a mybook.pdf output.

> mpbuild KINDLE mybook
	

The KINDLE version also produces a mybook.pdf file. In this case, the following typesetting parameters are modified:

• •

  the page size is scaled to an 800x600 aspect ratio, with minimal borders

• •

  the font is changed to a sans-serif family (epigrafica)

• •

  the math font is scaled down

Because of the small page size in the KINDLE version, please bear the following in mind:

• •

  “long” equations will have to be manually split across lines. Use the conditional inclusion macros to provide alternate versions of long equations.

• •

  when including figures, always specify the size in terms of textwidth, in order to automatically rescale the graphics.

> mpbuild HTML mybook [destination]
	

HTML compilation takes place in two steps, first the LaTeX manuscript is converted to XML and then the XML is converted to HTML; both operation are performed by LateXML. Important notes:

• •

  the script (optionally) pre-renders all the PsTricks figures in the manuscript’s file tree;

• •

  if specified, the resulting XHTML files will be placed in the destination folder;

• •

  the main file will be mybook.xhtml

• •

  the look and feel of the resulting web pages can be controlled by setting up a CSS file called mybook.css in the same folder as the main LaTeX file; see Section 3.5 for a brief discussion.

> mpbuild EPUB mybook
	

EPUB compilation requires first to compile the manuscript as HTML, and then to package all the necessary files into an mybook.epub file. The conversion HTML to EPUB is performed using Calibre. As in the HTML case, you can control the look and feel of the resulting eBook by providing a custom CSS mybook.css.

The HTML produced by LaTeXML contains CSS markers for all the meaningful parts of the text. Most of the time, the CSS class names are related to the LaTeX sectioning names, prepended by the suffix ltx_. So, for instance, you can change the attributes of a section title by specifying a set of CSS directives for the class .ltx_title_section:

.ltx_title_section {
  background: lightgray;
  padding: 10px 0px 10px 10px;
  border-radius: 6px;
}
	

or you can change captions like so:

.ltx_caption {
  width: 80%;
  margin: auto;
  font-style: italic;
}
	

Changes in the style once again address the relevant CSS tag; for instance, to eliminate the initial indentation in paragraphs use

.ltx_para > .ltx_p:first-child {
  text-indent: 0;
}
	

Please look at the provided examples and consult the LaTeXML documentation for more details.