Opened 7 years ago

Closed 7 years ago

#4572 enhancement closed fixed (fixed)

Improve lore2sphinx buildbot results for `projects/mail`

Reported by: khorn Owned by:
Priority: normal Milestone: Lore to Sphinx
Component: mail Keywords:
Cc: Jean Daniel Browne Branch: branches/lore2sphinx-mail-4572
branch-diff, diff-cov, branch-cov, buildbot
Author: jdb

Description

like #4566, except for projects/mail

Attachments (5)

index.rst (436 bytes) - added by Jean Daniel Browne 7 years ago.
index.2.rst (526 bytes) - added by Jean Daniel Browne 7 years ago.
mail/examples/index.rst
smtpclient.rst (28.9 KB) - added by Jean Daniel Browne 7 years ago.
Corrected verison of the SMTP tutorial
smtpclient-old.rst (29.3 KB) - added by Jean Daniel Browne 7 years ago.
Open version of the SMTP tutorial
smtpclient.xhtml.patch (17.0 KB) - added by Jean Daniel Browne 7 years ago.

Download all attachments as: .zip

Change History (18)

comment:1 Changed 7 years ago by khorn

Milestone: Lore to Sphinx

Changed 7 years ago by Jean Daniel Browne

Attachment: index.rst added

Changed 7 years ago by Jean Daniel Browne

Attachment: index.2.rst added

mail/examples/index.rst

Changed 7 years ago by Jean Daniel Browne

Attachment: smtpclient.rst added

Corrected verison of the SMTP tutorial

Changed 7 years ago by Jean Daniel Browne

Attachment: smtpclient-old.rst added

Open version of the SMTP tutorial

comment:2 Changed 7 years ago by Jean Daniel Browne

Cc: Jean Daniel Browne added
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):

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

#. 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?

comment:3 Changed 7 years ago by Jean-Paul Calderone

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.

Changed 7 years ago by Jean Daniel Browne

Attachment: smtpclient.xhtml.patch added

comment:4 in reply to:  3 ; Changed 7 years ago by Jean Daniel Browne

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.

comment:5 Changed 7 years ago by Thijs Triemstra

Component: coremail
Keywords: review added
Owner: Glyph deleted

Putting the patch up for review.

comment:6 in reply to:  4 Changed 7 years ago by 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.

comment:7 Changed 7 years ago by 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).

comment:8 Changed 7 years ago by Jean-Paul Calderone

Author: exarkun
Branch: branches/lore2sphinx-mail-4572

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

comment:9 Changed 7 years ago by Jean-Paul Calderone

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

refs #4572

comment:10 Changed 7 years ago by Jean-Paul Calderone

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

refs #4572

comment:11 Changed 7 years ago by Jean-Paul Calderone

Author: exarkunjdb
Keywords: review removed
Owner: set to Jean-Paul Calderone

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

comment:12 Changed 7 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

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

comment:13 Changed 7 years ago by <automation>

Owner: Jean-Paul Calderone deleted
Note: See TracTickets for help on using tickets.