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

Sat Jun 16 01:39:48 PDT 2012

I just tested the newest version of chkrst.py on the reST files in llvm/loc:

(design_and_overview.rst 10) Warning: Line exceeds 79 characters
(index.rst 65) Warning: Trailing whitespace detected
(mailing_lists.rst 20) Warning: Line exceeds 79 characters
(mailing_lists.rst 28) Warning: Line exceeds 79 characters
(subsystems.rst 7) Warning: Trailing whitespace detected
(subsystems.rst 9) Warning: Trailing whitespace detected
(subsystems.rst 11) Warning: Trailing whitespace detected
(subsystems.rst 13) Warning: Trailing whitespace detected
(subsystems.rst 15) Warning: Trailing whitespace detected
(subsystems.rst 16) Warning: Line exceeds 79 characters
(subsystems.rst 19) Warning: Trailing whitespace detected
(subsystems.rst 21) Warning: Trailing whitespace detected
(subsystems.rst 24) Warning: Trailing whitespace detected
(subsystems.rst 26) Warning: Trailing whitespace detected
(subsystems.rst 29) Warning: Trailing whitespace detected
(subsystems.rst 31) Warning: Trailing whitespace detected
(subsystems.rst 34) Warning: Trailing whitespace detected
(subsystems.rst 36) Warning: Trailing whitespace detected
(subsystems.rst 39) Warning: Trailing whitespace detected
(subsystems.rst 41) Warning: Trailing whitespace detected
(subsystems.rst 44) Warning: Trailing whitespace detected
(subsystems.rst 46) Warning: Trailing whitespace detected
(subsystems.rst 49) Warning: Trailing whitespace detected
(subsystems.rst 51) Warning: Trailing whitespace detected
(subsystems.rst 53) Warning: Trailing whitespace detected
(subsystems.rst 55) Warning: Trailing whitespace detected
(subsystems.rst 58) Warning: Trailing whitespace detected
(subsystems.rst 60) Warning: Trailing whitespace detected
(subsystems.rst 63) Warning: Trailing whitespace detected
(subsystems.rst 65) Warning: Trailing whitespace detected
(subsystems.rst 67) Warning: Trailing whitespace detected
(subsystems.rst 69) Warning: Trailing whitespace detected
(subsystems.rst 71) Warning: Trailing whitespace detected
(subsystems.rst 73) Warning: Trailing whitespace detected
(userguides.rst 15) Warning: Trailing whitespace detected
(userguides.rst 19) Warning: Trailing whitespace detected
(userguides.rst 24) Warning: Trailing whitespace detected
(userguides.rst 30) Warning: Trailing whitespace detected
(userguides.rst 42) Warning: Line exceeds 79 characters
(userguides.rst 44) Warning: Trailing whitespace detected
(userguides.rst 48) Warning: Trailing whitespace detected
(userguides.rst 52) Warning: Trailing whitespace detected
(userguides.rst 58) Warning: Trailing whitespace detected
(userguides.rst 59) Warning: Line exceeds 79 characters
(userguides.rst 61) Warning: Trailing whitespace detected
(userguides.rst 65) Warning: Trailing whitespace detected
(userguides.rst 66) Warning: Line exceeds 79 characters
(userguides.rst 69) Warning: Trailing whitespace detected
(userguides.rst 73) Warning: Trailing whitespace detected
(userguides.rst 78) Warning: Line exceeds 79 characters
(userguides.rst 81) Warning: Trailing whitespace detected

Please notice that I normally avoid going all the way to 80 characters
because 80 chars (as opposed to 79 chars) makes a mess of console output.
 It is highly likely that the "Line exceeds 79 characters" warnings are
simply examples of lines that are precisely 80 chars long.  If desired, I
can change the script to only warn if the line actually exeeds 80
characters, even though I think that would be counter to what's attempted
accomplished by using a line length of 80 chars.

I've attached the most recent version of chkrst.py.  I think we should
eventually check it into the LLVM source tree so that all reST authors can
run it and catch the most obvious problems before sending to *-commits.

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

> Almost there!
>
> Some finishing touches:
>
> 1. The link in userguides.rst should link to <faq> (the anchor at the top
> of FAQ.rst).
>
> 2. Please add FAQ.rst to the toctree in userguides.rst
>
> --Sean Silva
>
>
>
>
> On Fri, Jun 15, 2012 at 7:38 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>
>> 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/7379b473/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: chkrst.py
Type: application/octet-stream
Size: 3272 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120616/7379b473/attachment.obj>