LaTeX WWer tools

pglatex

pglatex (zipped source code and manuals) comprises programs (pglatex_check and pglatex_post) to facilitate Project Gutenberg white washers' task of compiling uploaded LaTeX documents. The source package contains a shell script, pglatex_fakepad, for PPers to test their LaTeX source files.

These tools work only on *nix (GNU/Linux, Mac OS X, Cygwin, etc.).

Input File Structure (for PPers)

Please consult the list of recently-posted projects for examples of pglatex-compliant source files. pglatex-compliant projects start at etext:31911. (Projects between etext:25155 and etext:31600 use now-obsolete command block syntax.)

Do keep in mind that the boilerplate, credits, and license text are not present in the uploaded source file. During white washing, these stanzas are automatically substituted in for "placeholder" lines whose format is described below.

A LaTeX file is pglatex-compliant if:

1. The preamble comment block contains
   • A command block, describing how the project is to be compiled (see below)
   • A PDF page count line
   • A \listfiles declaration
2. The document contains three placeholder tags, each surrounded by three consecutive asterisks and otherwise containing one of the words:
   • "Boilerplate" (example: *** Header boilerplate ***)
   • "Credits" (example: "*** Credits ***")
   • "License" or "Licence" (example: "*** PG licence text goes here ***")
3. The log file is appended. (The number of pages reported in the log file should match the PDF page count line.)

lprep configuration is strongly encouraged.

Important note: As of 2010, the active white washers do not speak LaTeX. Consequently, pglatex-compliance is required of all LaTeX files uploaded to Project Gutenberg. If needed, please ask for assistance in the LaTeX forum for post-processors.

Command Block

The command block comprises one or more consecutive lines, each consisting of a command name (and options), an optional declaration x<num> specifying the number of times the command is to be run, and an optional comment preceded by a hash mark ("#"). [Caution: This requirement is new as of April 2010.]

The following commands are recognized:

• pdflatex
• makeindex
• latex
• dvips
• ps2pdf
• dvipdfm

Sample command lines include:

• %% pdflatex x3 #(run pdflatex three times)
• %% dvips -t 8.5,11in
• %% makeindex -o FILE.nnd -t FILE.nlg FILE.ndx # Compile custom index, see below

Normally the extension of the input file (.tex, .idx, .dvi, or .ps) can be deduced automatically, and the name of the input file must not be specified explicitly.

The special string "FILE" expands during white washing to the base name of the LaTeX source file. In the makeindex command above, the input file's name is required in the command options. Since the file extension (here .ndx) cannot be deduced during white washing, the name of the file being operated upon (here FILE.ndx) must be given explicitly in the command block.

Page Count

The PDF page count should look like

• %% PDF pages: <number of pages>

Listfiles

A \listfiles command must appear in the preamble, placed on a line by itself. This command causes LaTeX to write detailed package version information to the log file. In the unlikely event your project mis-compiles at Project Gutenberg, the WWer can compare your package versions with those available at PG, a useful preliminary diagnostic.

Placeholder Tags

The placeholder tags may appear in the document body (normally in an alltt or verbatim environment, preceded by any necessary formatting commands), or in the preamble (wrapped in commands performing the actual formatting). In the latter case, the wrapping commands would appear in the document body where the boilerplate, credits, and license text are to appear.

lprep Configuration

The source file may contain an lprep configuration stanza, delimited by lines beginning

• ###

The start of an lprep stanza must be the first non-blank line after \end{document}.

Log file

The latest log file must be appended to the LaTeX source file immediately after the lprep stanza. pglatex will extract the number of pages (double-checking against the PDF Pages line) and summarize the LaTeX warnings for the WWer, comparing against the log file when the WWer compiles the project.

White Washer Work Flow

For illustration, suppose project.zip -- containing the LaTeX source file project.tex, compiled PDF project.pdf, and optionally an images/ directory -- is uploaded, and that the project is assigned the eBook number 00000.

These commands will process the project:

• unzip project.zip
• mv project.tex project.txt
• <run PG posting program on project.txt, generating 00000-8.txt>
• pglatex_check 00000-8.txt
• <verify 00000-lprep.txt, make corresponding corrections in 00000-WW.tex>
• pglatex_post 00000-WW.tex
• < push 00000.zip to the server>

Here are the tasks the commands perform:

1. Unpack the zip file and rename project.tex -> project.txt
2. Run the PG posting program on project.txt, generating 00000-8.txt. (Rename the file if necessary.) This file contains (in order) the PG boilerplate and credits, the PPer's LaTeX source with the log file removed, and the PG license.
3. Run pglatex_check on 00000-8.txt, generating
   • 00000-WW.tex (the primary source file)
   • 00000-WW.pdf (PDF compiled using the PPer's command block)
   • 00000-PP-notes.txt (the PPer's comments)
   • 00000-PP.tex (PPer's LaTeX file, with log file removed)
   • 00000-lprep.txt (lprep-ed text file from 00000-PP.tex, for gutchecking)
   • 00000-logs.log (summaries of LaTeX log files from PPer's and WWer's runs)
   • 00000-build (executable shell script capable of compiling the project)
4. Manually verify 00000-lprep.txt (as for a normal txt file), but make necessary corrections to 00000-WW.tex
5. Run pglatex_post on 00000-WW.tex, generating the file 00000.zip, which contains
   • 00000-t/00000-t.tex, 00000-t/images/ (LaTeX source and images/ directory)
   • 00000-t.zip (zipped LaTeX source and images)
   • 00000-pdf.pdf (compiled PDF, for final visual inspection and uploading)
   • 00000-pdf.zip (zipped PDF)

Once 00000.zip is pushed to the server, pglatex's temporary files may be safely deleted.

File Testing (for PPers)

If your platform has a C++ compiler and the GNU shell bash, you can use pglatex to pre-test your projects before uploading them. The source package contains a simple makefile. Running make docs builds the package, including the manuals, which should be consulted for detailed instructions.

The tools do not modify any source files, but you may wish to work with file copies (including the images/ directory) in a scratch directory to simplify cleanup.

First run pglatex_fakepad on your LaTeX source file; this creates a file named 00000-8.txt. Now proceed with Step 3 of the WWer instructions above.

Feedback

pglatex was a joint effort of adhere (implementation) and dcwilson (design and extensive guidance).

Please PM if you have questions, bug reports, comments, or other feedback.