On Sat, Jul 10, 2010 at 8:19 PM, Tim Allen email@example.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 firstname.lastname@example.org 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
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
was writing lore2sphinx, so I haven't really considered this.
So you're suggesting convert the man pages to Lore format -> use
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
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),
should have the base docs in a branch, and the "chunk tickets" referenced
the transition plan created. This is pretty much _exactly_ what I'd like
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. :)