[LLVMdev] Develop on trunk.

Thu Jun 14 09:19:43 PDT 2012

You can start off the Technical Writing FAQ if you want :)

Things I'm noticing as I read:

1. I'm not liking how sphinx is making each of the (sub)section headers
link to their entry in the Table of Contents; that seems useless. I'll
investigate how to disable this, if it is possible.

2. You're missing a trailing underscore for the link to GetElementPtr.html.
Same for GettingStarted.html#brokengcc

3. use syntax coloring for LLVM bitcode:
.. code-block:: llvm
and for C++:
.. code-block:: cpp
if you want to default the document to llvm bitcode highlighting you can do
.. highlight:: llvm
at the top of the document

Otherwise, it looks good! Anything else I find can be discussed on
llvm-commits. Send the patch! :)

For a future revision, I feel like it may be worth splitting some of these
"FAQ"s into a separate "troubleshooting" page. Some questions, like "in
what language is LLVM written?" are probably good FAQ questions. Things
like "when I configure, it finds the wrong C compiler" are probably better
suited to a "troubleshooting" page.

--Sean Silva

On Wed, Jun 13, 2012 at 10:08 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:

> Done.  Do you want to see it again or should I simply ship it off to
> llvm-commits?  The only thing I've changed from the original HTML is that
> I've changed a few missing code pieces into using code markup.  And now
> I've made the changes you requested and I think it looks really good: Each
> question being a subsection of its own works very well in my opinon.
>
> Oh, heck, I might as well attach the document here so you don't need to
> request it from me if you want it.
>
>
>
> 2012/6/14 Sean Silva <silvas at purdue.edu>
>
>> As I read, I'm writing stuff here things come to me:
>>
>> 1. Don't indent the list. Some of the other RST files do this, but it is
>> incorrect since it indents the list! The list is semantically "at the top
>> level" of indentation (it's not a sub-element of anything).
>>
>> 2. don't have that mini "table of contents" list at the beginning. sphinx
>> will generate that itself (albeit without the snippets, but your titles
>> should be descriptive enough) with the following directive
>> .. contents::
>>    :local:
>>
>> the :local: prevents the document itself from appearing as an extra level
>> of nestedness in the table of contents (it's just the title, which you
>> "already know" when reading).
>>
>> 3. the convention in reStructuredText is 3-space indent. don't ask me
>> why, I have no clue.
>>
>> 4. I'm not sure exactly how to markup the questions. The sphinx FAQ (
>> http://sphinx.pocoo.org/faq.html) marks it up as a definition list
>> (ctrl-f "definition list" http://sphinx.pocoo.org/rest.html). On the
>> other hand, the Python FAQs (e.g.
>> http://docs.python.org/py3k/faq/general.html) do it differently, with
>> each question as a sub-section. I don't really know the "right answer", but
>> try to choose a style that has a precedent (and communicate the precedent
>> to reviewers).
>>
>> 5. kind of in line with the last point, choose "header styles" that have
>> a precedent. The strongest precedent here I think is the Python docs style,
>> which is
>>
>> =====
>> Title
>> =====
>>
>> Major Division 1
>> ================
>>
>> Minor Division 1.1
>> ------------------
>>
>> Confusingly, Sphinx itself uses:
>>
>> Title
>> =====
>>
>> Major Division 1
>> ----------------
>>
>> Minor Division 1.1
>> ~~~~~~~~~~~~~~~~~~
>>
>> Let's just agree to use the Python style. Ok? It's really not that
>> important but it just has to be chosen and sooner is better than later for
>> these things. My incredibly weak "reason" for preferring the Python style
>> is that I've sometimes had to squint to tell apart ------ and ~~~~~~, but I
>> have never had that problem with ====== and -------. btw, if you use vim,
>> an easy way to make an ===== underline of the same width as the current
>> line is yypVr= and a similar command works for ----- or any other character.
>>
>> btw, if you haven't found out that sphinx generally puts a "show source"
>> link on the HTML it generates, you should be aware of it. it's really
>> useful to quickly see what the reST source code looks like corresponding to
>> a page. The easiest way to learn reST is probably to just browse existing
>> documentation. The python docs are a good one to look at.
>>
>> --Sean Silva
>>
>> On Wed, Jun 13, 2012 at 8:10 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>
>>> I just finished up the first draft of the FAQ translated verbatim from
>>> HTML to Sphinx.  Sphinx did puzzle me a few times but I got used to its
>>> approximate error messages and figured out what the problems were.
>>>
>>> Perhaps you could take a quick glance at this file and tell me if I am
>>> doing something wrong?  Otherwise I'll send it off to llvm-commits and see
>>> what they say.
>>>
>>>
>>> Thanks,
>>> Mikael
>>>
>>> 2012/6/14 Sean Silva <silvas at purdue.edu>
>>>
>>>> > 8. A Technical Writer FAQ (should include the Sphinx documentation
>>>> from the lld docs).
>>>>
>>>> I'm working on the Sphinx stuff; if you have any questions about
>>>> writing Sphinx docs feel free to ask.
>>>>
>>>> --Sean Silva
>>>>
>>>> On Wed, Jun 13, 2012 at 4:37 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>>>
>>>>> I think the best way that I can currently contribute to the project is
>>>>> through technical writing.  So I see myself as doing a serious, long-term
>>>>> project of extending the FAQ.  So, I can affirm that I want to really start
>>>>> working :)  This at the same time as I plan to regularly release an
>>>>> unofficial Windows distro of Clang with headers and libraries so people
>>>>> don't need to install MinGW to use Clang.
>>>>>
>>>>> I was myself thinking of a number of FAQs:
>>>>>
>>>>> 1. A General FAQ with high level questions like "What is the
>>>>> license?", "What is LLVM?", and "What is Clang?"  Something that lifts the
>>>>> newcomer up to a fairly knowledgable state in a short time.
>>>>> 2. An LLVM User FAQ that only deals with LLVM usage questions.
>>>>> 3. An LLVM Dev FAQ that only deals with LLVM development questions.
>>>>> 4. A Clang User FAQ that only deals with Clang usage questions.
>>>>> 5. A Clang Dev FAQ that only deals with Clang development questions.
>>>>> 6. A you-name-it User FAQ that (lld comes to mind)...
>>>>> 7. A you-name-it Dev FAQ that...
>>>>> 8. A Technical Writer FAQ (should include the Sphinx documentation
>>>>> from the lld docs).
>>>>>
>>>>> I know this probably seems overwhelming at first, but LLVM + Clang are
>>>>> two gigantic projects that really need thousands of questions and answers,
>>>>> not only 10-15.  Obviously, this won't materialize overnight, but I was
>>>>> thinking along that path.  I have plenty of time and my commitment to the
>>>>> project is 100 percent as I badly need it for my own compiler project.  I
>>>>> cannot stand coding on my compiler 24/7, so I figure I can use the breaks
>>>>> (days and weeks) to work on LLVM/Clang documentation.  That way I won't
>>>>> have to swim in deep water (code), but can stay safely near the beach for
>>>>> the time being.  Once I know enough about the project, I can perhaps jump
>>>>> in and begin coding myself.  But meanwhile, I can spend my energy on making
>>>>> the transition from noob to guru that much easier for others who want to
>>>>> join it.  I even see myself skimming through old posts on the mailing lists
>>>>> to gather useful stuff.  And, perhaps, we can over time work out a system
>>>>> where you guys voluntarily cc: me whenever you give a strategic or
>>>>> important explanation you'd like to see included in the FAQ.
>>>>>
>>>>> There are many, many things that I think could benefit from being
>>>>> documented in a FAQ manner.  For instance, how do you make an object file
>>>>> from a program that uses LLVM as its backend?  (You don't need to answer,
>>>>> it is only an example, even though I am very curious about finding out
>>>>> about this sometime).  Basically, I want to document what I learn while I
>>>>> transition from LLVM noob to advanced LLVM user (I doubt I'll make it to
>>>>> guru level, but advanced user is also fine for me).
>>>>>
>>>>> I'm printing your commit guidelines right after I send this reply.
>>>>>  They are highly useful and even the mailing lists ought to have some FAQ
>>>>> entries - probably in the General FAQ.
>>>>>
>>>>>
>>>>> 2012/6/14 Chandler Carruth <chandlerc at google.com>
>>>>>
>>>>>> On Wed, Jun 13, 2012 at 3:41 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>>>>>
>>>>>>> Guys, that was very interesting and useful stuff you preached there.
>>>>>>>  Mind if I make a patch to the FAQ and include it somewhere?
>>>>>>>
>>>>>>> "Q: When should I develop against a branch?  A: Only if you are
>>>>>>> making really big or controversial changes.  ... blah blah
>>>>>>>
>>>>>>> I am thinking that it would be highly useful for the project, if
>>>>>>> somebody (yours sincerely) took it upon himself to hunt and gather the very
>>>>>>> interesting bits that often pop up in these mailing lists.  As a newbie, I
>>>>>>> think the lists are very valuable, but you cannot expect people to always
>>>>>>> read all of the old stuff on the lists and as much as we all love Google's
>>>>>>> search engine (bing! bing!), it does always find the stuff you want to find
>>>>>>> (nearly, but not always).
>>>>>>>
>>>>>>
>>>>>> Yes, patches to the FAQ are very welcome.
>>>>>>
>>>>>> We should honestly organize the FAQ a bit differently if you want to
>>>>>> start really working to flesh it out with more useful information. I think
>>>>>> there should be three FAQs at least:
>>>>>>
>>>>>> 1) A FAQ for the LLVM Project, which is applicable to LLVM, Clang,
>>>>>> and often other subprojects. This would include the license section in the
>>>>>> current LLVM faq, and maybe some other points.
>>>>>>
>>>>>> 2) A FAQ for the LLVM codebase -- specific to the code, libraries,
>>>>>> and infrastructure in the primary project.
>>>>>>
>>>>>> 3) A Clang FAQ for the FE-specific stuff.
>>>>>>
>>>>>>
>>>>>> The current FAQ is mostly #2, with a bit of #1, and a lot of
>>>>>> out-of-date or flat out wrong information. The current FAQ could probably
>>>>>> stay as one page, or be two pages, but it should have a clear and well
>>>>>> deliniated split between #1 and #2. We should discuss creating #3 on
>>>>>> cfe-dev in a separate thread if you're interested.
>>>>>>
>>>>>>
>>>>>> If you're proposing patches, here are some suggestions as the
>>>>>> standard process may not work as well... which others may contradict if
>>>>>> they disagree... ;]
>>>>>>
>>>>>> - Patches to fix the formatting / structure should go directly to
>>>>>> llvm-commits
>>>>>>
>>>>>> - Patches to add a FAQ entry to section #1 above should at least go
>>>>>> to llvm-commits, llvmdev, and possibly a few of the mailing lists for
>>>>>> suprojects to get wider feedback.
>>>>>>
>>>>>> - Patches to add a FAQ entry to section #2 above should go to
>>>>>> llvm-commits and llvmdev.
>>>>>>
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> LLVM Developers mailing list
>>>>> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
>>>>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>>>>>
>>>>>
>>>>
>>>
>>>
>>> --
>>> -- Love Thy Frog!
>>>
>>
>>
>
>
> --
> -- Love Thy Frog!
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/a9d60bbd/attachment.html>