RST: Epubmaker bug tracker
Note: RST is no longer used at DP. Information on this page may be out of date.
Bugs, quirks and wishes for epubmaker
Mostly from issues reported in the RST clinic forum thread. TODO add some links to the specific discussion.
:alt: text not output in text
.. image:: myimage.png
:alt: alternate text
doesn't produce any output in text versions. Bug, feature or choice? (or -- conforms with WWers requirement?)
RST tags don't nest
This is a known RST limitation
Anonymous links did not work in pdf
.. _this target:
**try me**: go to `this target`_
was not ok. Fixed with epubmaker 0.3.16.
explicit link target not output in txt
This is a `link`_ This is the target pointed by my _`link`.
gave until 0.3.16:
This is a link This is the target pointed by my .
Now solved.
:coverpage: must be a jpeg file
No other graphic format accepted
Figure captions output in italics
And in txt formats with one set of underscores on each side.
image directive output as blank line in txt
The image directive puts an extra blank space in the text file where the directive was placed. It will look like a thought break of two blank lines.
blockqoute+aligned text makes two blank lines
Who could have stolen the tickets was a mystery, until a slip of paper was handed to Giles, the treasurer, which read:
“Leo Dunbar was hanging around the ticket
wagon last night. Better watch and search him.
.. class:: right
“A Friend.”
Giles lost no time in acting upon the suggestion given in the note. He ran to the dressing-tent and, finding a key to fit Leo’s trunk, opened it.
This does everything as expected, except it puts two blank lines before the signature.
imposed image aspect scaling fails in pdf
.. image:: mypicture.png
:height: 20ex
:width: 10ex
That is with an imposed scaled aspect ratio, produces the expected result in html, epub, but not in pdf (only the first of the two options given is honored), because the tex code becomes:
\includegraphics[height=20ex,width=1.000\textwidth,keepaspectratio=true]{mypicture.png}
Missing first level title makes faulty html
If a first level title is not present immediately after the meta block, the resulting html will contain <title/> that apparently causes problems with some browsers.
unknown class to remove the default styles
e.g. something like:
.. style:: title
:class: roman
to remove the default bold.
meta field language not honored in pdf
While building the pdf, in the intermediate .tex file, the declaration
:DC.Language: it
is not honored. One has in the corresponding .tex file
\usepackage{polyglossia}
\setdefaultlanguage{english}
As a result, the hyphenations are not correct (dozens of wrong ones).
Note: there is also the undocumented styling option
.. style:: document
:class: language-de
Perhaps that was Marcello had in mind. I succeed only in getting
WARNING:root:xetex: Package polyglossia Warning: No hyphenation patterns were loaded for `ngerman' WARNING:root:xetex: Package polyglossia Warning: \setlocalhyphenminuseless for unknown language ger
and still wrong hypenations.
long tables not split and omitted in pdf
The intermediate .tex uses the package longtable which should be capable of splitting large tables across multiple pages, but instead long tables cause "LaTeX Error: Float(s) lost."
text styles applied to paragraphs give one sided text symbols
.. class:: bold
D\ :superscript:`r` Marcello Perathoner
produces correct text
*Dr Marcello Perathoner*
as well as html, epub, pdf, but
.. class:: bold right
D\ :superscript:`r` Marcello Perathoner
produces
Dr Marcello Perathoner*
with only a trailing asterisk and still a correct html, epub, pdf. Same happens for any combinations of {bold, italics, gesperrt, small-caps} AND {left, right, center} (but not justify): all miss the opening * or _
classes larger and smaller not honored in 0.3.18
?
unitame uses fixed translation tables
Translations should be language dependent or overridable by the user. For instance it is useless to translate ü and ä to ue and ae in French, while it is desirable in German. It wolud also be very useful to handle automatically [Greek: ] transliterations via unitame. [forum reference]
:lb: behavior changed
Until 0.3.16 it was possible to use :lb: within titles. The :lb: role changed with 0.3.17 and that doesn't work. See RST:_PG_Extensions_to_RST#Line_Break
meta block mandatory
epubmaker 0.3.18 gives error if the source file does not contain a this minimal meta info:
.. -*- encoding: utf-8 -*-
.. meta:: :PG.Title: My Title :PG.Released: 9999-9-9 :PG.Rights: Public Domain
Earlier versions did not.
.. footnotes:: mandatory
Otherwise html links from footnote reference to footnote text don'twork (the reverse link does).
.. footnotes:: can be used only once per document
?
the directive should either be used with a named argument (e.g. ".. footnotes:: Footnotes") or with the option :local: . The latter can perhaps be spent more than once.
The presence of the pgfooter directive imposes that titles of level t2, t3 and t4 are underlined by ===, ---, ```, respectively, in compliance with the RST best practices. [Discussion on the dp2rst thread].
style modifiers not documented
Here are some useful ones:
.. style:: document
:class: text-transform-smartquotes
.. style:: title
:class: center blue gesperrt
.. style:: subtitle
:class: center red
.. style:: .subtitle.level-3
:class: center bold
.. style:: paragraph ..acts from here on -- use within a container::
:class: noindent
.. style:: section .. acts on all of the body text!
:class: center
.. style:: topic
:class: smaller
(Perhaps the stylable elements are a subset of the elements in [1])
autonumbered footnotes>100 introduce backspaces in txt
This happens in 8.txt and .txt, because four indented margin positions are allocated to the footnote number, and further ones are achieved by going left of the margin with backspaces. [forum report reference].
auto-symbol footnote produces *0* identifier in pdf
[*]_ produces a superscript *0* as footnote reference in pdf; output as expected in all other formats. [forum reference]
dropcap with images not honored in epub-noimages
If the dropcap directive is used without providing an image, the initial letter of the paragraph is rendered as bigger; if an image is provided, epub-images uses it according to the instruction, but epub-noimages does nothing - the typeface of the initial is plain. [forum report reference].
apostrophe following a dropcap
apostrophes ' [U+0027 APOSTROPHE] are transformed into ’ [U+2019 RIGHT SINGLE QUOTATION MARK], also in *-0.txt, except for the one following a dropcap. [forum report reference].
dropcaps' second argument
It's effect is visible only if a .dropspan style is specified. [forum report reference].
However, when degraded to txt, the initial is kept out of the _smallcaps_ (or _italic_, or *bold*) markup, which is ugly. [forum report reference].
vspace arguments no more supported
http://www.gutenberg.org/wiki/Gutenberg:PG_extensions_to_RST#vspace is wrong with epubmaker 0.3.18. Arguments `pb` and `pbr` are not known.
arbitrary transformation of φ into ϕ
φ [U+03C6 GREEK SMALL LETTER PHI] is proper for classical Greek; ϕ for mathematics.
groff work. [forum report reference].
parsed-literal:: directive issues
Spaces are not preserved in epub (need to be HARD spaces);
Footnotes within parsed-literal:: blocks misplaced in pdf.
multiline figure captions not allowed in lof::
Only single-line captions work if the document has a list-of-figures (built with the lof:: directive) [forum report reference].
[pg nn] produces no output in Line blocks
In html should produce a left margin page number, in epub a hovering tooltip with the number; it does normally, but not if [pg nn] apperas within a | block. Output is almost correct in pdf.
table columns identification for split-columns
The number of :widths:, :aligns: and :vertical-aligns: arguments required for a table:: with variable number of columns may be more than thought. [forum report reference] [further comment]
Epubmaker changelog
As announced by Marcello on the [Post-Processing with reStructuredText thread], and appearing in the file CHANGES in the epubmaker installation directory.
0.3.18
Allow unicode line separator U+2028 as line feed.
Fix XetexWriter bug with tables without explicit width.
Add language support in XetexWriter.
Tweaks for docutils 0.8
Support docutils-0.8-style :class: language-.
0.3.17
Fix line height of large text.
Fix images with spaces in src attribute.
0.3.16
Add image_dir to Xetex writer.
Use quotation environment instead of quote.
Don't automatically insert \frontmatter.
Page nos. for kindlegen 1.2.
Call kindlegen.
Integrate changes into PG environment.
0.3.15
Reduce vertical margin of images to 1 in TXT.
Fixed link targets in NROFF, PDF.
Report error on xetex errors.
Escape characters in PDF info.
0.3.14
Fixed crash on HTML comments in Kindle writer.
0.3.13
Start on Kindle writer.
Fix spurious space in PDF literal blocks with classes.
Fix `flat´ TOC.
Thin spaces between quotes made optional.
0.3.12
Add more front- and backmatter classes.
Insert thin space between quotes.
Generated List of Tables.
Generated List of Figures.
Emit warning instead of error on groff warnings.
Fix crash when last cell in row spans rows.
Add option vertical-aligns for tables.
Default width of image calculated assuming 980px window.
Fix docutils indentation bug in poetry.
0.3.11
Add option widths to tables.
Add option aligns to tables.
Add class norules for tables.
Generate typographically correct tables.
Don't overwrite images if src dir == working dir.
0.3.10
Bug fixes.
0.3.9
A different fix for figure and image centering on ADE.
(Calculate explicit left margin).
More work on PDF (Xetex) writer.
Added directives for pagination control.
0.3.8
Fix empty poetry lines on ADE.
Fix figure and image centering on ADE.
Fix thoughtbreak centering on ADE.
For push, zip RST into subdir with images.
Start implementing PDF (Xetex) writer.
0.3.7
Integrate changes into PG environment.
Fix more CR/LF issues on windows.
Fix cover image format conversion.
Zips a pushable file for the WWers.
0.3.6
Code cleanup.
Different CSS templates for RST -> HTML and RST -> EPUB.
0.3.5
Zips files up for PG.
0.3.4
Tell Tidy not to merge divs and spans.
More fixes to plain text encoding.
0.3.3
Implemented coverpages for Adobe ADE.
CSS changes because Adobe ADE chokes on !important.
RST dropcap directive: don't use image in EPUB.
0.3.2
Packaging changes.