<br><br><div class="gmail_quote">On Sat, Jul 10, 2010 at 8:19 PM, Tim Allen <span dir="ltr"><<a href="mailto:screwtape@froup.com">screwtape@froup.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im">On Sat, Jul 10, 2010 at 03:17:03PM -0500, Kevin Horn wrote:<br>
> On Sat, Jul 10, 2010 at 2:40 AM, Tim Allen <<a href="mailto:screwtape@froup.com">screwtape@froup.com</a>> wrote:<br>
</div><div class="im">> > That's probably enough feedback to be getting on with; most of the<br>
> > problems appear to be from normalising "\n" in Lore docs to "" instead<br>
> > of " ", and also from adding whitespace after things. It is generally<br>
> > looking pretty great, though!<br>
><br>
> Yeah, that's pretty much it. As I said above though, if you "fix" it one<br>
> place, it breaks in another, so I tried to balance things in such a way that<br>
> the least broken markup appears in the output.<br>
><br>
> Almost all of the remaining problems will need to be fixed manually.<br>
<br>
</div>It sounds like a lot of the manual fixes will involve rewriting<br>
things so that inline markup does not appear at the end of a sentence<br>
next to the punctuation. That seems like a recipe for awkward prose. :/<br></blockquote><div><br>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.<br>
<br>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).<br><br>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...<br>
<br>Let's just say there's a reason that there's not an official docutils tool to _create_ restructuredText.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im"><br>
> > Some extra thoughts:<br>
> > - The ReviewingDocumentation wiki page has a section called "Editing<br>
> > man pages" that describes how to turn the nicely-formatted<br>
> > manpages into Lore input files. Would it be possible to do that as<br>
> > part of the lore2sphinx run, have the manpages included in the<br>
> > Sphinx documentation, and from then on generate the manpages from<br>
> > the .rst files instead of the other way around?<br>
><br>
> Sphinx does have a man page builder now, but I don't think it existed when I<br>
> was writing lore2sphinx, so I haven't really considered this.<br>
><br>
> So you're suggesting convert the man pages to Lore format -> use lore2sphinx<br>
> to convert the resulting Lore docs to rst -> build as part of the Sphinx<br>
> process, yes?<br>
<br>
</div>Yes. At least for trial, there's a bunch of stuff that's *only* in the<br>
man page and not the online docs, and a bunch of stuff that's *only* in<br>
the online docs and not the man page (and stuff that's *only* in the<br>
core/development/policy section of the docs, and not in the Trial<br>
section...). Hopefully if they're all part of the same doc system, it'll<br>
be easier to have everything in the one place and easy to find.<br>
<div class="im"><br>
> I think this is a worthwhile idea, but I'd prefer to leave it until after<br>
> the main docs are converted (i.e. under a separate ticket). lore2sphinx can<br>
> be used on just the man files later on if need be, though it would take a<br>
> little mucking around.<br>
<br>
</div>Something to add to the "open ticket for: anything else???" section of<br>
your transition plan, then? :)<br></blockquote><div><br>Sounds like it.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im"><br>
> Thanks for the fantastic (and nicely detailed) feedback, Tim!<br>
><br>
> Please take a look at the transition plan. In a few days (maybe sooner), I<br>
> should have the base docs in a branch, and the "chunk tickets" referenced in<br>
> the transition plan created. This is pretty much _exactly_ what I'd like to<br>
> see in those "chunk tickets".<br>
<br>
</div>Having done pretty much the first two of your suggested "chunks" in my<br>
previous mail, they look to be about the right size.<br>
<div class="im"><br>
> Hopefully you haven't already burned up your brain staring at markup<br>
> issues. :) We could really use this kind of help throughout the<br>
> process.<br>
<br>
</div>I'm looking forward to learning a little more about Sphinx and ReST. :)<br>
<div><div></div><div class="h5"><br></div></div></blockquote></div><br><br>Kevin Horn<br>