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

[Sean Silva]

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/20120615/c97fa9bc/attachment.html>