Recent changes to User Guide

User Guide modified by Enrico SEGRE

Enrico SEGRE — Sun, 28 Apr 2013 07:57:26 -0000

--- v6
+++ v7
@@ -68,7 +68,8 @@

 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.
+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**

User Guide modified by Enrico SEGRE

Enrico SEGRE — Sun, 28 Apr 2013 07:55:41 -0000

--- v5
+++ v6
@@ -49,20 +49,32 @@
 + 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 PPer. The option **-n** helps comparing old and new page labels.
+  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.
+  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\}
+  \[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***

WikiPage User Guide modified by Enrico SEGRE

Enrico SEGRE — Tue, 01 Jan 2013 20:09:03 -0000

--- v4
+++ v5
@@ -6,7 +6,7 @@
   it at hand to make corrections.

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

 + start by running **dpanalyzer _yourproject.txt_**. Add the option -i utf8 if
   you're dealing with a pgdpcanada project.

WikiPage User Guide modified by Enrico SEGRE

Enrico SEGRE — Mon, 31 Dec 2012 21:15:42 -0000

--- v3
+++ v4
@@ -32,11 +32,11 @@
   ~~~~~~~~~~

   Look into the text editor at each of the offending lines for problems, and correct
-  them. Iterate until they are resolved. For a more verbose output, you can also peruse
-  the options **-r**, **-V**.
+  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
+  **\[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
@@ -49,7 +49,7 @@
 + 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 PPer.
+  png files_ given by the PPer. 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

WikiPage User Guide modified by Enrico SEGRE

Enrico SEGRE — Mon, 31 Dec 2012 21:08:54 -0000

--- v2
+++ v3
@@ -8,7 +8,7 @@
 + remember that **dpanalyzer -h** prints out the full list of available options,
   with little help about them.

-+ start by running **dpanalyzer \**. Add the option -i utf8 if
++ 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
@@ -26,7 +26,7 @@
     PASS 2: line markup verification

     line 36 : Line-preserving block containing extraneous elements
-    line 63 : Closed \*/ without opening
+    line 63 : Closed */ without opening
     line 69 : one Start Paragraph too much
     ...
   ~~~~~~~~~~
@@ -40,7 +40,7 @@
   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
+  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**

@@ -51,7 +51,7 @@
   and you prefer to refer to the _original_ page numbers rather than to the _names of the
   png files_ given by the PPer.

-+ If your book has footnotes, run **dpanalyzer -f \**. You will get a list of the
++ 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.

@@ -60,7 +60,7 @@
   neutralize all but one of the multiple references, e.g. by turning temporarily 
   \[1\] into \{1\}

-+ Run **dpanalyzer -T \** and **dpanalyzer -L \**.
++ 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.

WikiPage User Guide modified by Enrico SEGRE

Enrico SEGRE — Mon, 31 Dec 2012 21:02:45 -0000

--- v1
+++ v2
@@ -19,30 +19,30 @@
 + The stdout output may contain a report like:

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

-        track continuing paragraphs
+          track continuing paragraphs

-  PASS 2: line markup verification
+    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
-  ...
+    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 verbose output, you can also peruse the options
-  **-r**, **-V**.
+  Look into the text editor at each of the offending lines for problems, and correct
+  them. Iterate until they are resolved. For a more verbose output, you can also peruse
+  the options **-r**, **-V**.

   **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**
+  **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:

@@ -55,12 +55,13 @@
   occurrences of footnote references in text, and corresponding footnote identifiers in
   the note body. Check for inconsistencies.

-  **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\}
+  **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\}

 + Run **dpanalyzer -T \** and **dpanalyzer -L \**.
-  to get a sketchy Tabe of contents and a List of Figures printed on stdout. Check if
+  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.

WikiPage User Guide modified by Enrico SEGRE

Enrico SEGRE — Mon, 31 Dec 2012 20:59:43 -0000

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.
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 verbose output, you can also peruse the options
-r, -V.

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 PPer.
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.

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}

Run dpanalyzer -T \<yourproject.txt> and dpanalyzer -L \<yourproject.txt>.
to get a sketchy Tabe 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.

... to be contined as more functionality is added