All sounds good to me.  I actually did try to follow the Python style when I used the ^^^ thingies for the questions (they're called subsubsections).  <div><br></div><div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div><div>4. I'm not sure exactly how to markup the questions. The sphinx FAQ (<a href="http://sphinx.pocoo.org/faq.html" target="_blank">http://sphinx.pocoo.org/faq.html</a>) marks it up as a definition list (ctrl-f "definition list" <a href="http://sphinx.pocoo.org/rest.html" target="_blank">http://sphinx.pocoo.org/rest.html</a>). On the other hand, the Python FAQs (e.g. <a href="http://docs.python.org/py3k/faq/general.html" target="_blank">http://docs.python.org/py3k/faq/general.html</a>) do it differently, with each question as a sub-section. I don't really know the "right answer", but try to choose a style that has a precedent (and communicate the precedent to reviewers).</div>
</div></blockquote><div><br></div><div>Doing the definition list thing might work very well in this case because the subsubsection markup (that I now use) requires very long lines (far in excess of 80 chars per line) and I don't think a definition list would require anything more than 80 chars per line.  So I'll give it a try with definition lists and see what the result looks like.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div>5. kind of in line with the last point, choose "header styles" that have a precedent. The strongest precedent here I think is the Python docs style, which is</div>
</div></blockquote><div><br></div><div>Sounds good.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div>Let's just agree to use the Python style. Ok? It's really not that important but it just has to be chosen and sooner is better than later for these things. My incredibly weak "reason" for preferring the Python style is that I've sometimes had to squint to tell apart ------ and ~~~~~~, but I have never had that problem with ====== and -------. btw, if you use vim, an easy way to make an ===== underline of the same width as the current line is yypVr= and a similar command works for ----- or any other character.</div>
</div></blockquote><div><br></div><div>I agree with you that the tilde does not work well as a highlighter.  Also, I'm on Windows and I use SlickEdit - and occasionally gedit.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div><div>btw, if you haven't found out that sphinx generally puts a "show source" link on the HTML it generates, you should be aware of it. it's really useful to quickly see what the reST source code looks like corresponding to a page. The easiest way to learn reST is probably to just browse existing documentation. The python docs are a good one to look at.</div>
</div></blockquote><div><br></div><div>Yes, I actually did that with the Sphinx Primer itself. </div><div><br></div><div>Thanks for your review of the conversion.  I'll try to put your points into a new Tech Writer's FAQ, unless you want the honor yourself now that you are working on Sphinx documents.</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><span class="HOEnZb"><font color="#888888">
<div><br></div></font></span></div></blockquote></div>
</div>