No problem with the late reply; I figured you had earned a weekend off :-)<div><br></div><div>Here's the updated version.</div><div><br></div><div><br><br><div class="gmail_quote">2012/6/27 Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span><br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Just ran into this: <a href="http://pygments.org/docs/lexers/" target="_blank">http://pygments.org/docs/lexers/</a><br>
It has all the names of the different syntax highlighting modes.<br>
<br>
Please add a link. I think that it is still worthwhile to include the<br>
most common ones directly though.<br>
<br>
Also, sorry for the late reply.<br>
<span class="HOEnZb"><font color="#888888"><br>
--Sean Silva<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
On Fri, Jun 22, 2012 at 12:59 PM, Mikael Lyngvig <<a href="mailto:mikael@lyngvig.org">mikael@lyngvig.org</a>> wrote:<br>
> Here's the updated version. I've changed the name of the document to<br>
> "DocumentationFAQ" per your request for a change of title of the document.<br>
><br>
><br>
>><br>
>> This list does not cover a lot of cases, like adding a new page.´<br>
><br>
><br>
> I've changed the wording to explicitly state that new LLVM FAQs go to<br>
> llvm-commits and llvmdev. Likewise, new Clang FAQs go to cfe-commits and<br>
> cfe-dev.<br>
><br>
>> +How do I make special markups like ``notice`` and such?<br>
>> +-------------------------------------------------------<br>
>> This title is nonsensical given that ``notice`` isn't an admonition at<br>
>> all. Like I said, "warning" and "tip" are the representative examples,<br>
>> so they should be in the title.<br>
><br>
><br>
> Well, in my experience, you need the note admonition ten times as often as<br>
> the warning and tip admonitions. So I am just trying to help out the<br>
> newcomer here. But, I think I've changed it to reflect your desires.<br>
><br>
>> +.. note:: This is an example of a note admonition.<br>
>> + To make a note like this, you write:<br>
>> +<br>
>> + .. code-block:: rest<br>
>> +<br>
>> + .. note:: This is a note.<br>
>> This example is a bit misleading. It would be better if the note<br>
>> visible to the reader mirrored (as much as possible) the actual note<br>
>> that it is in. The content of the example note visible to the reader<br>
>> should be:<br>
>> +.. note:: This is an example of a note admonition.<br>
>> + To make a note like this, you write:<br>
>> + ...<br>
>> (so basically copy the note itself and indent it, putting in an<br>
>> ellipsis to avoid "infinite recursion" (but make sure it includes at<br>
>> least the title and a line of the body))<br>
><br>
><br>
> I ended up doing it somewhat differently: I made a note and then wrote how<br>
> to make it outside of it. It basically looked silly with a note including a<br>
> code sample.<br>
>><br>
>><br>
>> --Sean Silva<br>
>><br>
>> On Thu, Jun 21, 2012 at 1:56 PM, Mikael Lyngvig <<a href="mailto:mikael@lyngvig.org">mikael@lyngvig.org</a>><br>
>> wrote:<br>
>> > Hi Sean,<br>
>> ><br>
>> > Here's the updated version with your suggestions.<br>
>> ><br>
>> ><br>
>> > Regards,<br>
>> > Mikael<br>
>> > -- Disclaimer: I am not arrogant in real life, so if you perceive me as<br>
>> > being arrogant, you are to blame ;-)<br>
>> ><br>
>> > 2012/6/20 Sean Silva <<a href="mailto:silvas@purdue.edu">silvas@purdue.edu</a>><br>
>> >><br>
>> >> I specifically starred the previous one and have been wanting to get<br>
>> >> back<br>
>> >> to it. It is a pretty long document, so there is naturally a lot to say<br>
>> >> about it. I guess I'll abandon it now, as we can use this lightweight<br>
>> >> version as a starting point.<br>
>> >><br>
>> >> I was generally very impressed with the content and liked it. The<br>
>> >> Question&Answer style seemed to fit well with the nature of the<br>
>> >> material.<br>
>> >><br>
>> >> This lightweight Technical Writing FAQ seems to be excellent in that it<br>
>> >> distills the things you have learned from myself and other reviewers<br>
>> >> for<br>
>> >> your own documentation submissions; I think it will be highly<br>
>> >> beneficial for<br>
>> >> . If we all produced such distillations when we learned about a<br>
>> >> particular<br>
>> >> part of LLVM, then all of our documentation problems would be solved<br>
>> >> :-)<br>
>> >><br>
>> >> I choked on one particular thing that I couldn't quite put my finger<br>
>> >> on,<br>
>> >> but that I think I can articulate now. In my mind, I envision people<br>
>> >> contributing to the LLVM docs as having some experience with LLVM<br>
>> >> already.<br>
>> >> We can assume a number of things, such as, for example, that they know<br>
>> >> C++,<br>
>> >> so we can display a C++ fragment without any fanfare. I think that it<br>
>> >> is<br>
>> >> safe to assume that anybody that is going to be writing LLVM docs is<br>
>> >> going<br>
>> >> to have the source code checked out and be familiar with their<br>
>> >> version-control system. So a question like "How do I get access to the<br>
>> >> LLVM<br>
>> >> documentation source files?" need not exist. Perhaps "where are the<br>
>> >> LLVM<br>
>> >> docs files located?" and the answer would be "in the docs/ directory of<br>
>> >> the<br>
>> >> LLVM source tree". Leveraging assumptions like this can improve the<br>
>> >> documentation by making it briefer and more dense with information<br>
>> >> relevant<br>
>> >> to the audience. I'm sure the people on this list would be happy to<br>
>> >> provide<br>
>> >> feedback on any questions regarding whether something is a safe<br>
>> >> assumption.<br>
>> >><br>
>> >> Comments about the document itself:<br>
>> >><br>
>> >> +#. Raw HTML with a Cascading Style Sheet (CSS) file.<br>
>> >> I think you can just say "Raw HTML" here. CSS is presentational and not<br>
>> >> part of "writing the docs"<br>
>> >><br>
>> >> +The former is gradually being outphased in favor of the latter so you<br>
>> >> should<br>
>> >> I think you mean "phased-out". I have never seen "outphased" used<br>
>> >> before.<br>
>> >> Google hits for "outphased" are unrelated (or vaguely-related) to this<br>
>> >> usage.<br>
>> >><br>
>> >> +You basically edit, using an ordinary text editor (not a word<br>
>> >> processor),<br>
>> >> the<br>
>> >> I don't think this comment about a word processor is necessary.<br>
>> >> Remember<br>
>> >> your audience.<br>
>> >><br>
>> >> +Some hints:<br>
>> >> + [...]<br>
>> >> These are not "hints"; they are phrased as rules.<br>
>> >><br>
>> >> +#. reStructured Text files end in the extension ``.rst``.<br>
>> >> reStructuredText is one word.<br>
>> >><br>
>> >> +#. Keep each line, except section headers, at maximum 79 characters.<br>
>> >> LLVM convention is 80<br>
>> >><br>
>> >> + [...] But the entire Sphinx website is<br>
>> >> +full of interesting information relating to Sphinx.<br>
>> >> This sentence doesn't say anything. It is obvious that the Sphinx<br>
>> >> website<br>
>> >> will be about Sphinx, so all this is really saying is that the<br>
>> >> information<br>
>> >> there is "interesting". I think it would be better to say something<br>
>> >> useful,<br>
>> >> like "The Sphinx website contains thorough documentation about Sphinx<br>
>> >> usage<br>
>> >> and the reStructuredText format". Also "Sphinx website" should be a<br>
>> >> link to<br>
>> >> their homepage.<br>
>> >><br>
>> >> +A good trick is that most websites that use Sphinx offer a ``View<br>
>> >> code``<br>
>> >> The canonical name for this link is "Show Source". I have never seen<br>
>> >> "View<br>
>> >> code". Also, why is it monospaced? Quotes or italics is much more<br>
>> >> fitting. I<br>
>> >> would recommend leveraging this as part of this document by inviting<br>
>> >> the<br>
>> >> reader to click this link and have the source up side-by-side as they<br>
>> >> continue reading.<br>
>> >><br>
>> >> +What are ``llvm-commits`` and ``llvmdev``?<br>
>> >> This is another case where I think we can assume that the audience will<br>
>> >> be<br>
>> >> aware of what these are. It might still be beneficial to add an<br>
>> >> introductory<br>
>> >> sentence leading the section titled "How do I submit my changes to the<br>
>> >> LLVM<br>
>> >> documentation?" with the content<br>
>> >> "Changes should be submitted to the `mailing lists <mailing_lists>`_ as<br>
>> >> follows:"<br>
>> >><br>
>> >> +What markers should I use for chapter and section headers?<br>
>> >> The reST specification refers to these "markers" as "adornment styles"<br>
>> >><br>
>> >> <<a href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections" target="_blank">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections</a>><br>
>> >><br>
>> >> + Major Division 1 (Chapter)<br>
>> >> I don't think ==== means "chapter" at all. The Sphinx documentation<br>
>> >> <<a href="http://sphinx.pocoo.org/rest.html#sections" target="_blank">http://sphinx.pocoo.org/rest.html#sections</a>> mentions the breakdown for<br>
>> >> adornments used by the Python docs (which we are trying to follow), and<br>
>> >> it<br>
>> >> says ==== means "section"<br>
>> >><br>
>> >> +Avoid using the ``::`` operator. Instead, you have to use the<br>
>> >> ``code-block``<br>
>> >> +command.<br>
>> >> The Sphinx docs call :: a "marker", not an "operator"<br>
>> >> <<a href="http://sphinx.pocoo.org/rest.html#source-code" target="_blank">http://sphinx.pocoo.org/rest.html#source-code</a>>. And ``code-block`` is<br>
>> >> a<br>
>> >> "directive", not a "command". More importantly, the tone of these two<br>
>> >> sentences is completely contradictory. One says "avoid", while the<br>
>> >> other<br>
>> >> says "you have to". Better to say "Prefer to use the ``code-block``<br>
>> >> directive over a bare ``::`` marker to introduce code snippets"<br>
>> >><br>
>> >> +whenever there's code embedded in the text), you insert a<br>
>> >> ``code-block``<br>
>> >> +statement like this:<br>
>> >> Thank you for giving an example here! ``code-block`` is a "directive",<br>
>> >> not<br>
>> >> a "statement" though.<br>
>> >><br>
>> >> +The list is huge. Check it out at the `Pygments website<br>
>> >> +<<a href="http://pygments.org/languages/" target="_blank">http://pygments.org/languages/</a>>`_.<br>
>> >> It is confusing to mention Pygments out of the blue. You should briefly<br>
>> >> note that Pygments is the package that Sphinx uses for syntax<br>
>> >> highlighting<br>
>> >> before linking to the Pygments language list.<br>
>> >><br>
>> >> + [...] Unfortunately, there's no explicit list<br>
>> >> +of the actual names to use with ``code-blocks``<br>
>> >> OMG, yes! This is so annoying. Also, the "s" in ``code-blocks`` should<br>
>> >> be<br>
>> >> outside the `` `` quotes.<br>
>> >><br>
>> >> +[...]Here's a list of the most<br>
>> >> +commonly used languages in the LLVM world:<br>
>> >> It's not a list of languages, it's a list of names for those languages.<br>
>> >> "Here's a list of names for the most commonly used languages in the<br>
>> >> LLVM<br>
>> >> world"<br>
>> >><br>
>> >> +#. LLVM: ``llvm``<br>
>> >> I would say "LLVM IR" just to be extra clear.<br>
>> >><br>
>> >> +#. reStructured Text: ``rest``<br>
>> >> reST doesn't have a space before Text<br>
>> >><br>
>> >> +Why do my numbered lists not work?<br>
>> >> +----------------------------------<br>
>> >> Thank you for bringing this up, as it has the potential to be *very*<br>
>> >> confusing.<br>
>> >><br>
>> >> +How do I make special sections like ``notice`` and such?<br>
>> >> +--------------------------------------------------------<br>
>> >> +Check out ``.. note::`` and friends in `reStructured Text Directives<br>
>> >> +<<a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#note" target="_blank">http://docutils.sourceforge.net/docs/ref/rst/directives.html#note</a>>`_.<br>
>> >> The general name for these constructs is "admonitions". I think it<br>
>> >> would<br>
>> >> be worth mentioning that, since that is the key term for Googling to<br>
>> >> learn<br>
>> >> more about it. Also, the link should probably be<br>
>> >><br>
>> >> <<a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions" target="_blank">http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions</a>><br>
>> >> even though it appears to link to the same place. Also, "notice" isn't<br>
>> >> one<br>
>> >> of the admonitions, and admonitions aren't "sections". The<br>
>> >> representative<br>
>> >> examples of admonitions are "tip", "warning", and "note". Also, to be<br>
>> >> even<br>
>> >> more clear, I would put this actual question inside an admonition<br>
>> >> itself, as<br>
>> >> in<br>
>> >><br>
>> >> .. note::<br>
>> >> To make a note like this, do ...<br>
>> >> [...]<br>
>> >> There are also similar directives for "warning" and "tip", among<br>
>> >> others. The general name for these constructs is "admonitions", and a<br>
>> >> full<br>
>> >> reference can be found on the `reStructuredText specification<br>
>> >><br>
>> >> <<a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions" target="_blank">http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions</a>>`_.<br>
>> >><br>
>> >> Sorry for the 80-column violation, my mail client is not my usual<br>
>> >> editing<br>
>> >> environment.<br>
>> >><br>
>> >> --Sean Silva<br>
>> >><br>
>> >> On Tue, Jun 19, 2012 at 1:28 PM, Mikael Lyngvig <<a href="mailto:mikael@lyngvig.org">mikael@lyngvig.org</a>><br>
>> >> wrote:<br>
>> >>><br>
>> >>> Hi,<br>
>> >>><br>
>> >>> I've written a tiny, light-weight Technical Writing FAQ for those of<br>
>> >>> us<br>
>> >>> who venture into the land of converting existing HTML to Sphinx or<br>
>> >>> even<br>
>> >>> writing new documentation. I posted it to LLVMdev, but got not a<br>
>> >>> single<br>
>> >>> reply.<br>
>> >>><br>
>> >>> I have intentionally not linked it into the existing documentation<br>
>> >>> because I have no clue where to put it. I figure that the person who<br>
>> >>> checks<br>
>> >>> the document in, if it is accepted that is, can link it in somewhere.<br>
>> >>><br>
>> >>><br>
>> >>> Cheers,<br>
>> >>> Mikael<br>
>> >>> -- Disclaimer: I am not arrogant in real life, so if you perceive me<br>
>> >>> as<br>
>> >>> being arrogant, you are to blame ;-)<br>
>> >>><br>
>> >>> _______________________________________________<br>
>> >>> llvm-commits mailing list<br>
>> >>> <a href="mailto:llvm-commits@cs.uiuc.edu">llvm-commits@cs.uiuc.edu</a><br>
>> >>> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
>> >>><br>
>> >><br>
>> ><br>
>> ><br>
><br>
><br>
><br>
><br>
> --<br>
> -- Disclaimer: I am not arrogant in real life, so if you perceive me as<br>
> being arrogant, you are to blame ;-)<br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br>-- Love Thy Frog!<br>
</div>