[LLVMdev] Develop on trunk.

[Mikael Lyngvig]

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.

>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/7d1be2b9/attachment.html>