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

[Mikael Lyngvig]

Sometimes the # works, but not always.  It works earlier in the document.
 The remaining 80 char column violations are due to Sphinx not accepting
section titles to be broken across lines.

I figured you'd gone home for the day and submitted my patch - too early
once again.  I'll move the FAQ to the User Guides section and then
resubmit.  The other things should be okay already.

Here's an idea for Google (Google, google it!): Make Google+ so that it
displays the users on a world map and displays the current time of the
user, if you hover your cursor over somebody on the map.  I live and work
in Denmark so I am probably off everybody else by a factor of 6 to 9 hours,
which sometimes makes me react impatiently because I don't feel like
waiting until the next working day in the US.  And then convince everybody
to drop Facebook and use Google+ instead ;-)

2012/6/16 Sean Silva <silvas at purdue.edu>

> 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/20120616/ac244955/attachment.html>