[LLVMdev] Develop on trunk.

[Mikael Lyngvig]

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.

2012/6/14 Mikael Lyngvig <mikael at lyngvig.org>

> 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).
>
> 4. I'm not sure exactly how to markup the questions. The sphinx FAQ (
>> http://sphinx.pocoo.org/faq.html) marks it up as a definition list
>> (ctrl-f "definition list" http://sphinx.pocoo.org/rest.html). On the
>> other hand, the Python FAQs (e.g.
>> http://docs.python.org/py3k/faq/general.html) 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).
>>
>
> 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.
>
>
>> 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
>>
>
> Sounds good.
>
> 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.
>>
>
> 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.
>
> 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.
>>
>
> Yes, I actually did that with the Sphinx Primer itself.
>
> 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.
>
>>
>>


-- 
-- Love Thy Frog!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/418766a0/attachment.html>