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! >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120613/ee92c34b/attachment.html>
All sounds good to me. I actually did try to follow the Python style when I used the ^^^ thingies for the questions (they're called subsubsections). 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). >Doing the definition list thing might work very well in this case because the subsubsection markup (that I now use) requires very long lines (far in excess of 80 chars per line) and I don't think a definition list would require anything more than 80 chars per line. So I'll give it a try with definition lists and see what the result looks like.> 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 >Sounds good. 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. >I agree with you that the tilde does not work well as a highlighter. Also, I'm on Windows and I use SlickEdit - and occasionally gedit. 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. >Yes, I actually did that with the Sphinx Primer itself. Thanks for your review of the conversion. I'll try to put your points into a new Tech Writer's FAQ, unless you want the honor yourself now that you are working on Sphinx documents.> >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/7d1be2b9/attachment.html>
As far as I can determine, with my marginal knowledge of Sphinx, the 80 chars per line limit is going to be exceeded no matter if we use subsections or definition lists. The advantage, IMHO, of using subsections is that the questions themselves make it into the table of contents, right where you want them to be so as many as possible notice them even if they don't think of searching the document or Google. So I'll make it using subsections and fix it to match your style guidelines. 2012/6/14 Mikael Lyngvig <mikael at lyngvig.org>> All sounds good to me. I actually did try to follow the Python style when > I used the ^^^ thingies for the questions (they're called subsubsections). > > 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). >> > > Doing the definition list thing might work very well in this case because > the subsubsection markup (that I now use) requires very long lines (far in > excess of 80 chars per line) and I don't think a definition list would > require anything more than 80 chars per line. So I'll give it a try with > definition lists and see what the result looks like. > > >> 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 >> > > Sounds good. > > 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. >> > > I agree with you that the tilde does not work well as a highlighter. > Also, I'm on Windows and I use SlickEdit - and occasionally gedit. > > 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. >> > > Yes, I actually did that with the Sphinx Primer itself. > > Thanks for your review of the conversion. I'll try to put your points > into a new Tech Writer's FAQ, unless you want the honor yourself now that > you are working on Sphinx documents. > >> >>-- -- Love Thy Frog! -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/418766a0/attachment.html>
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>
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>