RST:Post-Processing Verifier's Guide to RST
Note: RST is no longer used at DP. Information on this page may be out of date.
PPVing a RST submission. To be completed.
A personal view--EastEriq
Most of the PPVing process shouldn't really be much different from the traditional one (at least for what I understand -- I have never PPVed so far, nor PPed anything but in RST).
The first thing the PPVer would do is to download the PPer submission, and to generate all the output formats -- either having installed his local copy of epubmaker or via the online epubmaker server. Epubmaker will already report compilation errors, in case serious ones are present (but see below about unitame conversion errors).
Having generated an html and a text version, the PPVer can decide which one to attack first, and do all the ordinary consistency checks: sanity of all internal links, quality and sizes of the images specifically for the first; correctness of the text, scannos for both; spacing and line length for the latter, to name just some. Honestly, the content of the book is foremost; neither the PPVer shouldn't be put off by a new markup language, nor the PPer neglect diligence in producing the e-text - the result counts, not the wizardry in coding it.
The PPVer may also want to have a look at the automatically generated result in epub format (very popular nowadays as download from PG) and in pdf. The latter is not usually generated by the WWers and sort of optional, but usually the nicest in rendering. A conscious PPer may have played out optimizations.
The PPVer should be aware that:
- being RST a markup format intended to generate ALL outputs, the PPer may have had to compromise in order to produce an acceptable result simultaneously in all of them.
- the PPer may therefore be resistant to do ad hoc, separate modifications to the produced html, text, ... file and to submit them instead of his RST master.
- the RST PPer has no control on the html and epub CSS. He has only a few options on palette for paragraph and blocktext formatting and indentation.
- the RST PPer has no control on font choice, cannot produce text wrapping around images, and similar sophisticated rendering effects.
- the RST PPer has very little control on paragraph spacing -- PPVers please don't complain on three blank lines before subsection titles.
However, the RST PPer can control, even quite finely:
- general styles for chapters, section titles, etc; font sizes (even basic colors); internal hyperlinks;
- RST allows a limited control (not too much, but not nothing) on placement of footnotes, citation references, itemized or enumerated lists, and such.
The options available in RST to create tables (including Tables of Contents, Indexes, Lists of Illustrations) are limited. The PPer may have decided to simplify the printed presentation, trying to retain the essential semantic structure of the book -- the PPVer should be aware of that.
As a technical issue, multiple blank spaces (between words) in the RST are insignificant for the html, pdf, epub outputs, but are taken into account for the text ones. Thus the PPer has a very limited headroom for forcing (or breaking by mistake) alignments in txt by typing multiple spaces. On the other side, being RST a very synthetic markup language, it is very easy to mess up the formatting half of a book just because of a wrongly indented source text line.
A PPVer literate in RST can be very helpful in suggesting how to code particular situations, but, once more, PPVing is much more about quality control of the produced text than being a code guru. I think a good PPVer could even ignore completely the RST syntax and vagueries, and yet provide valuable critical feedback to the PPer.
latex errors and warnings
TBC
groff warnings
like "can't break line" -- TBC
unitame errors
unitame is the transcoding program internally used for converting the utf8 native RST representation (recommended, thought not mandatory) to the various text outputs - including latin-1 and ascii. It is the module converting em-dashes to -- and “” quotes to " ones. Unfortunately, its fixed set of translation rules does not include Greek transliteration (with a noisy complaint -- unhandled chars: {~....} ), nor is proper for all languages (e.g, diereses ä ö ü are unavoidably translated as Umlauts, ae oe ue). The PPer may have ground for asking for the ascii version not to be generated from the RST master, ignoring thus the epubmaker "errors". The PPVer should evaluate the case.
link to RST Index Page