[llvm-commits] [PATCH] LLVM FAQ converted into reST format

[Sean Silva]

I don't know what's happening with the "#." stuff. The sphinx reST primer
even gives that as an example, so maybe it is something in the LLVM sphinx
configuration.

I would hold off on putting the FAQ at the top of the index. That change
can be made later if there is a perceived need.

> The C backend change never made it into the reST file because it was a
manually written TOC entry without any text block.
Good to see that you are on top of this :)

Other than some 80-column violations this LGTM.

For the final patch, you should probably include the following three things:
1. add the FAQ.rst file that we've been looking at here
2. remove the FAQ.html file
3. link this file into a toctree (to avoid Sphinx warnings)

--Sean Silva

On Fri, Jun 15, 2012 at 2:50 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:

> The numbered lists are driving me crazy!  No matter what I try, they end
> up being numbered 1, 1, 1, and not 1, 2, 3.  Do you have any experience
> with this?  The embedded bulletted list shows up properly.  I use #.
> because I prefer that to 1. I could number the list manually, but that kind
> of defeats the whole purpose of using Sphinx (IMHO).  This is about the
> numbered list in the "I'd like to write a self-hosting compiler..." section.
>
> I'll munge about and try not to create havoc (sometimes I feel like an
> elephant in a glass retail store).
>
> The C backend change never made it into the reST file because it was a
> manually written TOC entry without any text block.
>
>
> 2012/6/15 Sean Silva <silvas at purdue.edu>
>
>> Hi Mikael,
>>
>> It seems like the ugly underlining that Michael mentioned is actually a
>> CSS problem and not a document structure problem. Michael Spencer and I
>> are working on updating the CSS to avoid it.
>>
>> Also, you should prepare this as a patch that creates the reST file and
>> removes the FAQ.html file and links the reST FAQ into the main toctree
>> somehow, in order to avoid the conflict between FAQ.html and the generated
>> FAQ.rst -> FAQ.html.
>>
>> btw, there was a recent change I caught out of the corner of my eye to
>> the FAQ removing references to the C backend. Could you doublecheck to make
>> sure that those changes get pulled into your reST version? Thanks.
>>
>> --Sean Silva
>>
>> On Fri, Jun 15, 2012 at 1:46 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>
>>> I don't seem to be able to make it fit in 80 chars.  For instance, the
>>> numbered lists require more than 80 chars and Sphinx won't accept them if
>>> they are broken into multiple lines.  The same goes for the questions:
>>> Several Sphinx commands must fit within a line for Sphinx to accept them.
>>>  I've tried backquoting the end-of-line character (text text text \), but
>>> that didn't work either.
>>>
>>> It all looked very nice in my end, but I didn't use the LLVM
>>> configuration of Sphinx as I don't know where to get it from.
>>>
>>> I got some pointers to the SVN repository for the FAQ, but the first
>>> didn't include the FAQ and the second gave me a cycle while trying an SVN
>>> pull.  What URL do you use to pull out the documentation for LLVM?
>>>
>>> 2012/6/15 Michael Spencer <bigcheesegs at gmail.com>
>>>
>>>> On Fri, Jun 15, 2012 at 2:25 AM, Mikael Lyngvig <mikael at lyngvig.org>
>>>> wrote:
>>>> > Can't really make a patch file as it is a new file based on FAQ.html
>>>> from
>>>> > the website.
>>>> >
>>>> > Changes are:
>>>> >
>>>> >    1. The format is now reST instead of HTML.
>>>> >    2. A few (like two or three) missing code markups have been added.
>>>> >    3. Sphinx code-blocks are now used for all kinds of code: bash, c,
>>>> and
>>>> > llvm.
>>>> >
>>>> > Other than that, the file should be a faithful and precise conversion
>>>> from
>>>> > HTML to reST.
>>>> >
>>>> >
>>>> > Cheers,
>>>> > Mikael
>>>>
>>>> It needs to be 80-col except for underlined headers. Also it needs to
>>>> be linked from a toctree and properly integrated. It also currently
>>>> conflicts with the FAQ.html that gets copied in so I had to rename it
>>>> to even see what it looked like.
>>>>
>>>> Each header is currently getting underlined by Sphinx, this looks
>>>> pretty weird. It should be using a different header level.
>>>>
>>>> - Michael Spencer
>>>>
>>>
>>>
>>> _______________________________________________
>>> llvm-commits mailing list
>>> llvm-commits at cs.uiuc.edu
>>> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120615/f9f8b6c0/attachment.html>