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

Mikael Lyngvig mikael at lyngvig.org
Tue Jun 19 12:57:56 PDT 2012 

Wow!  "I strongly disagree with the direction that you have taken this
script" :-)  I have merely recoded your AWK stuff into a Python script.  I
had some issues with quoting and AWK on Windows, probably a user error, and
therefore I spent like 10 minutes making a small script.  If you don't like
it, don't use it.

My editor does support using three spaces instead of a tab and even trims
extraneous whitespace at the end of the line (I use SlickEdit) (I didn't
use SlickEdit at first because I first had to add a new file extension to
it).

I have no plans whatsoever for extending the functionality of the script.
 And I didn't have any prior to receiving your mail - exactly because that
would require a reST parser and I don't feel any desire to write such a
parser.

So, easy now, the world's not going to crash and burn because I made a 50
line Python script :-)

I think the part about warning about too long or too short section headers
ought to be part of Sphinx.  As for checking too long lines, well, they
might as well do that now that they are busy parsing the source file.

If the requirements where of a very specific nature (such as a feature to
disallow all four-letter words when writing in English), I'd agree with
you.

But let's rest the case: I have already submitted the idea to the Sphinx
group, but I took great care to write "I" instead of "they" (you) or even
"we".  They'll probably laugh right up my face and do nothing about it and
the world will probably begin revolving once again.


-- 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 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/041eae24/attachment.html>

More information about the llvm-commits mailing list