Improve lore2sphinx buildbot results for `projects/mail`

[khorn]

like #4566, except for projects/mail

[jdb]

mail/examples/index.rst

[jdb]

Corrected verison of the SMTP tutorial

[jdb]

Open version of the SMTP tutorial

[jdb]

The mail documentation chunk is composed of three rst files: two short listings and one sizeable tutorial:

doc/projects/mail
|-- examples
|   `-- index.rst
|-- index.rst
`-- tutorial
    `-- smtpclient
        `-- smtpclient.rst

The transformation is almost correct, there are two bugs that show in HTML (they show especially in the file mail/tutorial/smtpclient/smtpclient.rst):

1. there is a space missing a space before an italic or preformatted markup (not always reproduceable). This bug is a problem as it disables the markup.

   ex: look for the text : "use by``twistd`` ." The original xhtml was "use by <code>twistd</code>.</p>". Because of the missing space, the markup is incorrect and the four backquotes can be read untransformed in html.

2. there is always extra space in the middle of:

   • an underline or preformatted string, or a link: (":ref:`link` ,")
   • a dot, comma, parenthesis, colon, apostrophy

   ex: look for the text : "*application service* ."

Often both bugs happen on the same chunk of text. Here are two other minor bugs of the rst file which do not show in HTML:

• four or even six unneeded blank lines between text blocks while one was enough
• weird paragraph fill (lines sometimes 30 characters long, sometimes 150)

Attached are the three rst files corrected by hand. Also the version buggy version of the tutorial is attached.

Question: is there a repository of restructured text that I can commit the version corrected by hand?

[exarkun]

Apparently #4566 didn't explain that the idea here is not to hand-fix the rst output, but to fix the Lore input so that the output comes out looking better.

[jdb]

Replying to exarkun:

Apparently #4566 didn't explain that the idea here is not to hand-fix the rst output, but to fix the Lore input so that the output comes out looking better.

Attached is a patch to the smtpclient xhtml/lore input where no text markup follows a newline character. This seems to fix the problem of rst markup being visible in HTML because of a missing space in the rst file.

Concerning the problem of the extra space created between a markup and a final dot, I haven't found a way yet to "adapt" the xhtml.

Does someone have trick for getting rid of the extra space?

It is also possible to rephrase each sentence so that no markuped expressions is in the end of a sentence (we do not want to do this I guess). It is also possible to leave this minor bug unfixed and fix it later on in the rst source.

[thijs]

Putting the patch up for review.

[Screwtape]

Replying to jdb:

Concerning the problem of the extra space created between a markup and a final dot, I haven't found a way yet to "adapt" the xhtml.

Yeah, I believe the plan is to fix the generated ReST markup after we throw the switch and make the Sphinx docs the official ones.

[khorn]

Yes, that is indeed the plan. Once this set of tickets has been completed, we'll convert to Sphinx and then clean up the remaining issues with another set of tickets. There are some issues which are just very difficult to translate automatically (as jdb has discovered).

[exarkun]

(In [29968]) Branching to 'lore2sphinx-mail-4572'

[exarkun]

(In [29969]) Apply smtpclient.xhtml.patch

refs #4572

[exarkun]

(In [29970]) Correct two more whitespace issues which cause lore2sphinx to emit bogus restructured text

refs #4572

[exarkun]

Thanks. This looks good, except for a couple extra changes I made above. Merging.

[exarkun]

(In [29972]) Merge lore2sphinx-mail-4572

Author: jdb Reviewer: exarkun Fixes: #4572

Various changes to the Twisted Mail documentation to improve the results of the lore2sphinx tool.