[llvm-commits] [PATCH] Convert SystemLibrary documentation to RST

[Sean Silva]

-* `System Library <SystemLibrary.html>`_
+* :ref:`system_library`

You can use :doc: for this.

+.. _system_library:
+
+==============
+System Library
+==============

The anchors at the top are from before I knew about :doc: and thought
I had to put a manual anchor at the top so I could use :ref:. I'm
planning on someday fixing all of these up, but there's
higher-priority work at the moment (like getting everything into rst
in the first place (btw, thanks for helping out!)).

+Don't Include System Headers
+============================

In the original document, this section and all the others after it are
h3's under the "Keeping LLVM Portable" h2, and I think that structure
should be preserved (just change ======= to ----------).

With those changes, it LGTM.

BTW, you might find the tool `pandoc` useful (maybe you are already
using it?). It generally does a pretty decent job of converting the
main content, although it will require some hand-tweaking afterward. A
few tips if you choose to use pandoc in the future:

* pandoc uses different adornments for title/section/subsection/etc.
It uses single ===== for the title, then ------ for section and ~~~~~
for subsection (I forget the rest, but you'll see them if you need).
These can be cleaned up really easily by just manually changing the
title to be double ======, then a couple commands like `g/^-\+$/s/-/=`
will whip it into shape.
* pandoc will convert the HTML table of contents to a bona-fide reST
equivalent. You can just delete this, since Sphinx will automatically
generate the table of contents if desired (`.. contents::`).
* HTML can nest certain things which reST can't. e.g. in reST you
can't have a link be monospace, or have something both italic and
monospace. pandoc isn't very smart about this and will output invalid
reST, but a quick glance over the file will easily catch these, and
sphinx will give some warnings too.
* pandoc will sometimes copy over the "Validated HTML" buttons and
botch them. Just delete them.

+Bug 351
+=======
+See `bug 351 <http://llvm.org/PR351>`_ for further details on the progress of
+this work.

You can probably kill this in a separate commit after this patch goes
in; the bug appears to have been resolved years ago.

-- Sean Silva

On Sun, Nov 18, 2012 at 7:42 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> Hello,
>
> The attached patch converts SystemLibrary.html to RST.  Please take a look.
>
> Dmitri
>
> --
> main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
> (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/