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

Sean Silva silvas at purdue.edu
Tue Jun 19 11:01:07 PDT 2012


> I have now submitted the three checks as a proposal for new features in
Sphinx in the sphinx-dev Google group.

I don't think this is a good idea. The things that your script checks are
mostly style issues that are a matter of personal opinion. This proposal is
tantamount to asking Clang to implement style checking for some particular
style. Imagine the silliness: "warning: class `unordered_map` should be
spelled `UnorderedMap`"; it would be madness.

To be clear, I strongly disagree with the direction that you have taken
this script.

That being said, I encourage you to use the script for your own personal
use if your editor does not support a straightforward way of making sure
that these blemishes do not occur. For example, if your editor does not
support setting tabs to 3 spaces for reStructuredText and you have to
manually put in 3 spaces every time, then it will make sense to have a
linter script like this that checks if you messed up.

Regardless, I think that your time would be better-spent focusing on the
content of the document, rather than cosmetic aspects of the source code;
converting HTML to rst is primarily a cosmetic change, which is why I have
been so nagging about cosmetic things, but in general, the content is
*much* more important. It is always possible to go back and mechanically
fix cosmetic aspects, whereas making sure that the document is coherent and
well-written is much more difficult to go back and repair.

--Sean Silva

On Tue, Jun 19, 2012 at 4:55 AM, Mikael Lyngvig <mikael at lyngvig.org> wrote:

> I have now submitted the three checks as a proposal for new features in
> Sphinx in the sphinx-dev Google group.
>
> Also, I accidentally stumbled across this article - perhaps you can use
> that for something?
> https://groups.google.com/forum/?fromgroups#!topic/sphinx-dev/BNemWMhcXAw
> (Robin, a Doxygen bridge to Sphinx).
>
>
> -- Disclaimer: I am *not* arrogant in real life, so if you perceive me as
> being arrogant, you are to blame ;-)
>
> 2012/6/19 Sean Silva <silvas at purdue.edu>
>
>> I would discourage you from investing too much time into chkrst.py
>> without incorporating a complete and correct reStructuredText parser.
>>
>> --Sean Silva
>>
>>
>> On Sat, Jun 16, 2012 at 1:39 AM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>
>>> 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/20120619/367f3c5c/attachment.html>


More information about the llvm-commits mailing list