User Guide

Practical use of dpanalyzer

• download your project file in dp marked txt format (not TEI), save it under
  some name of your choice, and open it in your favourite text editor, to have
  it at hand to make corrections.

• remember that dpanalyzer -h prints out the full list of available options,
  with little help about them (reported here.)

• start by running dpanalyzer yourproject.txt. Add the option -i utf8 if
  you're dealing with a pgdpcanada project.

• unless you were so lucky to have had top-class foofers, expect dpanalyzer
  to report several warnings, and to terminate with "Problems found, stopping".
  Don't worry, that is pretty much normal, and it is what the tool is for.
  Now you have the overview of the formatting errors of your file, globally.

• The stdout output may contain a report like:

~~~~~~~~~
PASS 1: parse the file at line level

      track continuing paragraphs

PASS 2: line markup verification

line 36 : Line-preserving block containing extraneous elements
line 63 : Closed */ without opening
line 69 : one Start Paragraph too much
...

~~~~~~~~~~

Look into the text editor at each of the offending lines for problems, and correct
them. Iterate until they are resolved. For a more detailed output, you can also peruse
the options -r, -V, -c.

Note: dpanalyzer is strict in requiring that /* */ blocks do not contain
[Illustration]s or /# #/ blockquotes; it is very common to find frontispieces
violating that.

Note: if your book happens to have clauses within square brackets within figure
captions or foot/sidenotes, like [Greek: ], and they may happen to fall at the end
of a line, or if the book has unmatched ] or [, all facts which can confuse
the parser, it may be yelpful to add the option dpanalyzer -b

After you resolved the first line-parsing complaints:

• at any time you can provide a true page numbers list with the option -p. This may be
  helpful in the further reports if you're inspecting the page images of the book,
  and you prefer to refer to the original page numbers rather than to the names of the
  png files given by the PMer. The option -n helps comparing old and new page labels.

• If your book has footnotes, run dpanalyzer -f yourproject.txt. You will get a list of the
  occurrences of footnote references in text, and corresponding footnote identifiers in
  the note body. Check for inconsistencies, which most of the time denote formatting errors.
  The format of footnote labels can be fine-tuned with the option -S.

Note: dpanalyzer at the moment assumes a 1 to 1 corrrespondence. Footnotes referred
to multiple times in the text are not yet supported. If that is your case, you have to
neutralize all but one of the multiple references, e.g. by turning temporarily
[1] into [\1] or anything the like.

• Run dpanalyzer -T yourproject.txt and dpanalyzer -L yourproject.txt.
  to get a sketchy Table of contents and a List of Figures printed on stdout. Check if
  Chapters ans Sections appear to have been marked as they should, and if all the
  expected figures are found.

Now you are ready to generate some output. Decide which format you want to concentrate on,
and tell it to with the option -o [at the time of writing, only -o html is
implemented]. dpanalyzer -o html -f yourproject.txt generates a file yourproject.html
in the current directory, overwriting silently any existing one.

• Footnotes placement (e.g. immediately after the paragraph they are referred to, at the end
  of the chapter or at the end of the book) is controlled by thye option -F

Preview the generated output (e.g., the html in a browser) and keep modifying options and the
input file until the result is reasonably good to move on from there. At that point, you can
start PPing.

... to be contined as more functionality is added