[LLVMdev] Develop on trunk.

Wed Jun 13 22:08:59 PDT 2012

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/a1730199/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: FAQ.rst
Type: application/octet-stream
Size: 17998 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/a1730199/attachment.obj>