[Twisted-Python] Lore to Sphinx Conversion Progress Report 6

[Kevin Horn]

On Sat, Jul 10, 2010 at 8:19 PM, Tim Allen <screwtape at froup.com> wrote:

> On Sat, Jul 10, 2010 at 03:17:03PM -0500, Kevin Horn wrote:
> > On Sat, Jul 10, 2010 at 2:40 AM, Tim Allen <screwtape at froup.com> wrote:
> > > That's probably enough feedback to be getting on with; most of the
> > > problems appear to be from normalising "\n" in Lore docs to "" instead
> > > of " ", and also from adding whitespace after things. It is generally
> > > looking pretty great, though!
> >
> > Yeah, that's pretty much it.  As I said above though, if you "fix" it one
> > place, it breaks in another, so I tried to balance things in such a way
> that
> > the least broken markup appears in the output.
> >
> > Almost all of the remaining problems will need to be fixed manually.
>
> It sounds like a lot of the manual fixes will involve rewriting
> things so that inline markup does not appear at the end of a sentence
> next to the punctuation. That seems like a recipe for awkward prose. :/
>

Not necessarily.  There are ways around a lot of these things, but they make
the markup a bit more complex and thus more complicated to generate
automatically.

For example, if the markup requires that there be a space, but you don't
actually want a space there, you insert an 'escaped space' ("\ ", that's a
backslash-space).

But the exact rules for what can abut the beginning and end of inline markup
are more complicated than that, and accounting for every special case would
be....er...

Let's just say there's a reason that there's not an official docutils tool
to _create_ restructuredText.


>
> > > Some extra thoughts:
> > >    - The ReviewingDocumentation wiki page has a section called "Editing
> > >      man pages" that describes how to turn the nicely-formatted
> > >      manpages into Lore input files. Would it be possible to do that as
> > >      part of the lore2sphinx run, have the manpages included in the
> > >      Sphinx documentation, and from then on generate the manpages from
> > >      the .rst files instead of the other way around?
> >
> > Sphinx does have a man page builder now, but I don't think it existed
> when I
> > was writing lore2sphinx, so I haven't really considered this.
> >
> > So you're suggesting convert the man pages to Lore format -> use
> lore2sphinx
> > to convert the resulting Lore docs to rst -> build as part of the Sphinx
> > process, yes?
>
> Yes. At least for trial, there's a bunch of stuff that's *only* in the
> man page and not the online docs, and a bunch of stuff that's *only* in
> the online docs and not the man page (and stuff that's *only* in the
> core/development/policy section of the docs, and not in the Trial
> section...). Hopefully if they're all part of the same doc system, it'll
> be easier to have everything in the one place and easy to find.
>
> > I think this is a worthwhile idea, but I'd prefer to leave it until after
> > the main docs are converted (i.e. under a separate ticket).  lore2sphinx
> can
> > be used on just the man files later on if need be, though it would take a
> > little mucking around.
>
> Something to add to the "open ticket for: anything else???" section of
> your transition plan, then? :)
>

Sounds like it.


>
> > Thanks for the fantastic (and nicely detailed) feedback, Tim!
> >
> > Please take a look at the transition plan.  In a few days (maybe sooner),
> I
> > should have the base docs in a branch, and the "chunk tickets" referenced
> in
> > the transition plan created.  This is pretty much _exactly_ what I'd like
> to
> > see in those "chunk tickets".
>
> Having done pretty much the first two of your suggested "chunks" in my
> previous mail, they look to be about the right size.
>
> > Hopefully you haven't already burned up your brain staring at markup
> > issues. :) We could really use this kind of help throughout the
> > process.
>
> I'm looking forward to learning a little more about Sphinx and ReST. :)
>
>

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20100710/134dbab6/attachment.html>