As far as I can determine, with my marginal knowledge of Sphinx, the 80 chars per line limit is going to be exceeded no matter if we use subsections or definition lists.  The advantage, IMHO, of using subsections is that the questions themselves make it into the table of contents, right where you want them to be so as many as possible notice them even if they don't think of searching the document or Google.  So I'll make it using subsections and fix it to match your style guidelines.<br>
<br><div class="gmail_quote">2012/6/14 Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span><br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
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"><div class="im"><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><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 class="im">
<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><div>Sounds good.</div><div class="im"><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><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 class="im"><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><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><font color="#888888">
<div><br></div></font></span></div></blockquote></div>
</div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br>-- Love Thy Frog!<br>