> <span style="font-family:arial,sans-serif;font-size:13px;background-color:rgb(255,255,255)">I have now submitted the three checks as a proposal for new features in Sphinx in the sphinx-dev Google group.</span><div><font face="arial, sans-serif"><br>
</font></div><div><font face="arial, sans-serif">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.</font></div>
<div><font face="arial, sans-serif"><br></font></div><div><font face="arial, sans-serif">To be clear, I strongly disagree with the direction that you have taken this script.</font></div><div><font face="arial, sans-serif"><br>
</font></div><div><font face="arial, sans-serif">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.</font></div>
<div><font face="arial, sans-serif"><br></font></div><div><font face="arial, sans-serif">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.</font></div>
<div><font face="arial, sans-serif"><br></font></div><div><font face="arial, sans-serif">--Sean Silva<br></font><br><div class="gmail_quote">On Tue, Jun 19, 2012 at 4:55 AM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I have now submitted the three checks as a proposal for new features in Sphinx in the sphinx-dev Google group.<div><br>
</div><div>Also, I accidentally stumbled across this article - perhaps you can use that for something?
<a href="https://groups.google.com/forum/?fromgroups#!topic/sphinx-dev/BNemWMhcXAw" target="_blank">https://groups.google.com/forum/?fromgroups#!topic/sphinx-dev/BNemWMhcXAw</a> (Robin, a Doxygen bridge to Sphinx).</div>
<div class="im HOEnZb"><div><br></div>
<div><br></div><div>-- Disclaimer: I am <b>not</b> arrogant in real life, so if you perceive me as being arrogant, you are to blame ;-) </div></div><div class="HOEnZb"><div class="h5"><div><br><div class="gmail_quote">2012/6/19 Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span><br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I would discourage you from investing too much time into chkrst.py without incorporating a complete and correct reStructuredText parser.<span><font color="#888888"><div>
<br></div></font></span><div><span><font color="#888888">--Sean Silva</font></span><div><div><br><br><div class="gmail_quote">On Sat, Jun 16, 2012 at 1:39 AM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I just tested the newest version of chkrst.py on the reST files in llvm/loc:<div><br></div><div><div>(design_and_overview.rst 10) Warning: Line exceeds 79 characters</div>
<div>(index.rst 65) Warning: Trailing whitespace detected</div>
<div>(mailing_lists.rst 20) Warning: Line exceeds 79 characters</div><div>(mailing_lists.rst 28) Warning: Line exceeds 79 characters</div><div>(subsystems.rst 7) Warning: Trailing whitespace detected</div><div>(subsystems.rst 9) Warning: Trailing whitespace detected</div>
<div>(subsystems.rst 11) Warning: Trailing whitespace detected</div><div>(subsystems.rst 13) Warning: Trailing whitespace detected</div><div>(subsystems.rst 15) Warning: Trailing whitespace detected</div><div>(subsystems.rst 16) Warning: Line exceeds 79 characters</div>
<div>(subsystems.rst 19) Warning: Trailing whitespace detected</div><div>(subsystems.rst 21) Warning: Trailing whitespace detected</div><div>(subsystems.rst 24) Warning: Trailing whitespace detected</div><div>(subsystems.rst 26) Warning: Trailing whitespace detected</div>
<div>(subsystems.rst 29) Warning: Trailing whitespace detected</div><div>(subsystems.rst 31) Warning: Trailing whitespace detected</div><div>(subsystems.rst 34) Warning: Trailing whitespace detected</div><div>(subsystems.rst 36) Warning: Trailing whitespace detected</div>
<div>(subsystems.rst 39) Warning: Trailing whitespace detected</div><div>(subsystems.rst 41) Warning: Trailing whitespace detected</div><div>(subsystems.rst 44) Warning: Trailing whitespace detected</div><div>(subsystems.rst 46) Warning: Trailing whitespace detected</div>
<div>(subsystems.rst 49) Warning: Trailing whitespace detected</div><div>(subsystems.rst 51) Warning: Trailing whitespace detected</div><div>(subsystems.rst 53) Warning: Trailing whitespace detected</div><div>(subsystems.rst 55) Warning: Trailing whitespace detected</div>
<div>(subsystems.rst 58) Warning: Trailing whitespace detected</div><div>(subsystems.rst 60) Warning: Trailing whitespace detected</div><div>(subsystems.rst 63) Warning: Trailing whitespace detected</div><div>(subsystems.rst 65) Warning: Trailing whitespace detected</div>
<div>(subsystems.rst 67) Warning: Trailing whitespace detected</div><div>(subsystems.rst 69) Warning: Trailing whitespace detected</div><div>(subsystems.rst 71) Warning: Trailing whitespace detected</div><div>(subsystems.rst 73) Warning: Trailing whitespace detected</div>
<div>(userguides.rst 15) Warning: Trailing whitespace detected</div><div>(userguides.rst 19) Warning: Trailing whitespace detected</div><div>(userguides.rst 24) Warning: Trailing whitespace detected</div><div>(userguides.rst 30) Warning: Trailing whitespace detected</div>
<div>(userguides.rst 42) Warning: Line exceeds 79 characters</div><div>(userguides.rst 44) Warning: Trailing whitespace detected</div><div>(userguides.rst 48) Warning: Trailing whitespace detected</div><div>(userguides.rst 52) Warning: Trailing whitespace detected</div>
<div>(userguides.rst 58) Warning: Trailing whitespace detected</div><div>(userguides.rst 59) Warning: Line exceeds 79 characters</div><div>(userguides.rst 61) Warning: Trailing whitespace detected</div><div>(userguides.rst 65) Warning: Trailing whitespace detected</div>
<div>(userguides.rst 66) Warning: Line exceeds 79 characters</div><div>(userguides.rst 69) Warning: Trailing whitespace detected</div><div>(userguides.rst 73) Warning: Trailing whitespace detected</div><div>(userguides.rst 78) Warning: Line exceeds 79 characters</div>
<div>(userguides.rst 81) Warning: Trailing whitespace detected</div><div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><div>
<div><br></div><br><div class="gmail_quote">2012/6/16 Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span><br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Almost there!<div><br></div><div>Some finishing touches:<br><div><br></div><div>1. The link in userguides.rst should link to <faq> (the anchor at the top of FAQ.rst).</div><div><br></div><div>2. Please add FAQ.rst to the toctree in userguides.rst</div>
<span><font color="#888888">
<div><br></div></font></span><div><span><font color="#888888">--Sean Silva</font></span><div><div><br><div><br></div><div><br><br><div class="gmail_quote">On Fri, Jun 15, 2012 at 7:38 PM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Thank you again! <div><br></div><div>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.</div>
<div><br></div><div>The AWK script didn't work; probably because of the way Windows handles ' characters: </div>
<div><br></div><div> awk: 'BEGIN</div><div> awk: ^ invalid char ''' in expression</div><div><br></div><div>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.</div>
<div><div>
<div><br></div><div><div class="gmail_quote">2012/6/16 Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span><br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
1. I'm seeing lots of trailing whitespace. If you have sed available you can fix it quickly with<div>sed -i -e 's/\s\+$//' FAQ.rst</div><div><br></div><div>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.<br>
<div><br></div><div>3. Your underline for the subheading "What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``?"</div><div>is too long. If you have cygwin installed or otherwise have access to unix tools you can run:</div>
<div><br></div><div>cat FAQ.rst | awk 'BEGIN { RS=""; FS="\n" } $2 ~ /[-=][-=]+/ && length($1) != length($2) { print NR, $1 }'</div><div><br></div><div>to proactively catch these mismatches in the future. It prints out the line-number and the offending heading of any mismatched headers.</div>
<div><br></div><div>4. Sphinx is emitting warnings because FAQ.rst is not linked into any toctree. You can find documentation about sphinx doctrees at <<a href="http://sphinx.pocoo.org/concepts.html" target="_blank">http://sphinx.pocoo.org/concepts.html</a>></div>
<div><br></div><div>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.</div>
<div><br></div><div>--Sean Silva</div><div><br><div class="gmail_quote"><div><div>On Fri, Jun 15, 2012 at 3:28 PM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div><div>Author: Mikael Lyngvig</div><div>Subject: FAQ.html converted into reStructured Text for use with Sphinx (it looks so good now!)</div>
<div><br></div>New patch (this is an actual "svn diff" instead of just a loose file) including all requested changes:<div>
<br></div><div> 1. Lines are now only 80 chars long.</div><div> 2. Incorrect links have been repaired (missing _ at end of cross-reference).</div><div> 3. FAQ.html is dead and has been deleted.</div>
<div> 4. FAQ.rst has been added.</div><div> 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.</div>
<div><br></div><div>Cheers,</div><div>Mikael</div><div><br></div>
<br></div></div>_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@cs.uiuc.edu" target="_blank">llvm-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
<br></blockquote></div><br></div></div>
</blockquote></div><br></div>
</div></div></blockquote></div><br></div></div></div></div></div>
</blockquote></div><br></div></div></div>
</blockquote></div><br></div></div></div>
</blockquote></div><br>
</div>
</div></div></blockquote></div><br></div>