<div class="gmail_quote"><div>Here's the updated version. I've changed the name of the document to "DocumentationFAQ" per your request for a change of title of the document.</div><div><br></div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">This list does not cover a lot of cases, like adding a new page.´</blockquote><div><br></div><div>
I've changed the wording to explicitly state that new LLVM FAQs go to llvm-commits and llvmdev. Likewise, new Clang FAQs go to cfe-commits and cfe-dev.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+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></blockquote><div><br></div><div>Well, in my experience, you need the note admonition ten times as often as the warning and tip admonitions. So I am just trying to help out the newcomer here. But, I think I've changed it to reflect your desires.</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+.. 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></blockquote><div><br></div><div>I ended up doing it somewhat differently: I made a note and then wrote how to make it outside of it. It basically looked silly with a note including a code sample. </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span><font color="#888888"><br>
--Sean Silva<br>
</font></span><div><div><br>
On Thu, Jun 21, 2012 at 1:56 PM, Mikael Lyngvig <<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>> 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" target="_blank">silvas@purdue.edu</a>><br>
>><br>
>> I specifically starred the previous one and have been wanting to get 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 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 for<br>
>> your own documentation submissions; I think it will be highly beneficial for<br>
>> . If we all produced such distillations when we learned about a particular<br>
>> part of LLVM, then all of our documentation problems would be solved :-)<br>
>><br>
>> I choked on one particular thing that I couldn't quite put my finger 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 already.<br>
>> We can assume a number of things, such as, for example, that they know C++,<br>
>> so we can display a C++ fragment without any fanfare. I think that it is<br>
>> safe to assume that anybody that is going to be writing LLVM docs is 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 LLVM<br>
>> documentation source files?" need not exist. Perhaps "where are the LLVM<br>
>> docs files located?" and the answer would be "in the docs/ directory of the<br>
>> LLVM source tree". Leveraging assumptions like this can improve the<br>
>> documentation by making it briefer and more dense with information relevant<br>
>> to the audience. I'm sure the people on this list would be happy to provide<br>
>> feedback on any questions regarding whether something is a safe 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 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 processor),<br>
>> the<br>
>> I don't think this comment about a word processor is necessary. 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 website<br>
>> will be about Sphinx, so all this is really saying is that the information<br>
>> there is "interesting". I think it would be better to say something useful,<br>
>> like "The Sphinx website contains thorough documentation about Sphinx usage<br>
>> and the reStructuredText format". Also "Sphinx website" should be a link to<br>
>> their homepage.<br>
>><br>
>> +A good trick is that most websites that use Sphinx offer a ``View code``<br>
>> The canonical name for this link is "Show Source". I have never seen "View<br>
>> code". Also, why is it monospaced? Quotes or italics is much more fitting. I<br>
>> would recommend leveraging this as part of this document by inviting 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 be<br>
>> aware of what these are. It might still be beneficial to add an introductory<br>
>> sentence leading the section titled "How do I submit my changes to the 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>
>> <<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 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 a<br>
>> "directive", not a "command". More importantly, the tone of these two<br>
>> sentences is completely contradictory. One says "avoid", while the 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 ``code-block``<br>
>> +statement like this:<br>
>> Thank you for giving an example here! ``code-block`` is a "directive", 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 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 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 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 would<br>
>> be worth mentioning that, since that is the key term for Googling to learn<br>
>> more about it. Also, the link should probably be<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 one<br>
>> of the admonitions, and admonitions aren't "sections". The representative<br>
>> examples of admonitions are "tip", "warning", and "note". Also, to be even<br>
>> more clear, I would put this actual question inside an admonition 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 full<br>
>> reference can be found on the `reStructuredText specification<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 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" target="_blank">mikael@lyngvig.org</a>><br>
>> wrote:<br>
>>><br>
>>> Hi,<br>
>>><br>
>>> I've written a tiny, light-weight Technical Writing FAQ for those of us<br>
>>> who venture into the land of converting existing HTML to Sphinx or even<br>
>>> writing new documentation. I posted it to LLVMdev, but got not a 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 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 as<br>
>>> being arrogant, you are to blame ;-)<br>
>>><br>
>>> _______________________________________________<br>
>>> llvm-commits mailing list<br>
>>> <a href="mailto:llvm-commits@cs.uiuc.edu" target="_blank">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>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><span>-- Disclaimer: I am <b>not</b> arrogant in real life, so if you perceive me as being arrogant, you are to blame ;-)</span><br>