[llvm-commits] [PATCH] FAQ converted from HTML to reST (2nd try)

[Mikael Lyngvig]

One more check added: If the line is too long.  Let me know if there's
anything else that can reasonably be checked.  Perhaps if lists are
indented or not

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

> Thank you again!
>
> All issues fixed.  Here is the file so that you may check it out again, if
> you so wish, before I waste more bandwidth on half-baked patches.
>
> The AWK script didn't work; probably because of the way Windows handles '
> characters:
>
>    awk: 'BEGIN
>    awk: ^ invalid char ''' in expression
>
> If you are up to it and have the time for it, you could perhaps some day
> make a small Python script that performs the checks you want of the rst
> files?  I can also do it, if you so prefer.
>
> 2012/6/16 Sean Silva <silvas at purdue.edu>
>
>> 1. I'm seeing lots of trailing whitespace. If you have sed available you
>> can fix it quickly with
>> sed -i -e 's/\s\+$//' FAQ.rst
>>
>> 2. There are still 2 (non-header) lines that are going past 80-columns.
>> They are the paragraph text under the first and last subheading under the
>> "License" heading.
>>
>> 3. Your underline for the subheading "What is this ``llvm.global_ctors``
>> and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``?"
>> is too long. If you have cygwin installed or otherwise have access to
>> unix tools you can run:
>>
>> cat FAQ.rst | awk 'BEGIN { RS=""; FS="\n" } $2 ~ /[-=][-=]+/ &&
>> length($1) != length($2) { print NR, $1 }'
>>
>> to proactively catch these mismatches in the future. It prints out the
>> line-number and the offending heading of any mismatched headers.
>>
>> 4. Sphinx is emitting warnings because FAQ.rst is not linked into any
>> toctree. You can find documentation about sphinx doctrees at <
>> http://sphinx.pocoo.org/concepts.html>
>>
>> 5. I wouldn't add the FAQ to index.rst in the same patch. This patch
>> should focus solely on replacing FAQ.html with FAQ.rst. By doing it this
>> way, we can focus on reST-style things for this patch. A future patch can
>> then move it to the front page, and will naturally serve as a forum for
>> discussion for the decision to do that.
>>
>> --Sean Silva
>>
>> On Fri, Jun 15, 2012 at 3:28 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>
>>> Author: Mikael Lyngvig
>>> Subject: FAQ.html converted into reStructured Text for use with Sphinx
>>> (it looks so good now!)
>>>
>>> New patch (this is an actual "svn diff" instead of just a loose file)
>>> including all requested changes:
>>>
>>>    1. Lines are now only 80 chars long.
>>>    2. Incorrect links have been repaired (missing _ at end of
>>> cross-reference).
>>>    3. FAQ.html is dead and has been deleted.
>>>    4. FAQ.rst has been added.
>>>    5. The FAQ has been added as the very first item on the documentation
>>> page (so that everybody sees it).  This may not be what you want so let me
>>> know if I should move it to the User Guides section instead.
>>>
>>> Cheers,
>>> Mikael
>>>
>>>
>>> _______________________________________________
>>> 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/bce58b67/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: chkrst.py
Type: application/octet-stream
Size: 2829 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120616/bce58b67/attachment.obj>