On Sat, Jul 10, 2010 at 8:19 PM, Tim Allen <screwtape@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@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