<html><body><div style="color:#000; background-color:#fff; font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:16px"><div dir="ltr" id="yui_3_16_0_1_1437615339254_2237753"><span id="yui_3_16_0_1_1437615339254_2237827">Separate from questions about whether Sphinx should handle numbered code lines</span></div><div id="yui_3_16_0_1_1437615339254_2237842" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">properly (it should), a style question about whether we should be numbering everything.</span></div><div dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">I am finding lots of different approaches in the docs.</span></div><div dir="ltr"><br><span id="yui_3_16_0_1_1437615339254_2237827"></span></div><div id="yui_3_16_0_1_1437615339254_2238091" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">I would posit that, for LONG code sections, numbered lines are a pretty good idea although,</span></div><div id="yui_3_16_0_1_1437615339254_2238093" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">in most cases, I would advocate for breaking those up into smaller sections that have discussions.</span></div><div id="yui_3_16_0_1_1437615339254_2238025" dir="ltr"><br><span id="yui_3_16_0_1_1437615339254_2237827"></span></div><div id="yui_3_16_0_1_1437615339254_2238027" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">I see the following types of displays:</span></div><div id="yui_3_16_0_1_1437615339254_2238029" dir="ltr"><br><span id="yui_3_16_0_1_1437615339254_2237827"></span></div><div id="yui_3_16_0_1_1437615339254_2238031" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">- Sequence of shell commands -- I advocate for no line numbers</span></div><div id="yui_3_16_0_1_1437615339254_2238033" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">- Files, usually either configuration files or raw source code</span></div><div id="yui_3_16_0_1_1437615339254_2238035" dir="ltr"><br><span id="yui_3_16_0_1_1437615339254_2237827"></span></div><div id="yui_3_16_0_1_1437615339254_2238037" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> Here, I vacillate. The only good reason I see for numbered lines in a small file display</span></div><div id="yui_3_16_0_1_1437615339254_2238040" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> is if one is going to use those numbers in the discussion of the file. But that can be hard</span></div><div id="yui_3_16_0_1_1437615339254_2238070" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> to maintain unless the line numbers in the code fragment are automagically correlated with</span></div><div id="yui_3_16_0_1_1437615339254_2238099" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> the line numbers in the discussion.</span></div><div dir="ltr"><br><span id="yui_3_16_0_1_1437615339254_2237827"></span></div><div dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> I have seen some code samples that have embedded comments but are still numbered.</span></div><div id="yui_3_16_0_1_1437615339254_2238229" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> This seems rather superfluous. I actually prefer code samples in documentation that don't</span></div><div id="yui_3_16_0_1_1437615339254_2238227" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> include the code comments but, again, I know there are times when this makes sense and</span></div><div id="yui_3_16_0_1_1437615339254_2238192" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827"> one can even argue that it's a more "natural" way for geeks to get the information.</span></div><div id="yui_3_16_0_1_1437615339254_2238211" dir="ltr"><br><span id="yui_3_16_0_1_1437615339254_2237827"></span></div><div id="yui_3_16_0_1_1437615339254_2238233" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">I would favor leaving most options open but it would be nice if our Markup Conventions gave</span></div><div id="yui_3_16_0_1_1437615339254_2238235" dir="ltr"><span id="yui_3_16_0_1_1437615339254_2237827">some guidelines to help people out.</span> I'll take the action to write up the results of this discussion.</div><div id="yui_3_16_0_1_1437615339254_2238253" dir="ltr"><br></div><div id="yui_3_16_0_1_1437615339254_2238254" dir="ltr">meg</div><div id="yui_3_16_0_1_1437615339254_2238256" dir="ltr"><br></div><blockquote id="yui_3_16_0_1_1437615339254_2237802" style="border-left: 2px solid rgb(16, 16, 255); margin-left: 5px; margin-top: 5px; padding-left: 5px;"> <div id="yui_3_16_0_1_1437615339254_2237801" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1437615339254_2237800" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1437615339254_2237799" dir="ltr"> <hr id="yui_3_16_0_1_1437615339254_2238238" size="1"> <font id="yui_3_16_0_1_1437615339254_2237798" face="Arial" size="2"> <b><span style="font-weight:bold;">From:</span></b> Christian Berendt <christian@berendt.io><br> <b><span style="font-weight: bold;">To:</span></b> "openstack-docs@lists.openstack.org" <Openstack-docs@lists.openstack.org> <br> <b id="yui_3_16_0_1_1437615339254_2237806"><span id="yui_3_16_0_1_1437615339254_2237805" style="font-weight: bold;">Sent:</span></b> Monday, July 27, 2015 2:28 PM<br> <b><span style="font-weight: bold;">Subject:</span></b> [OpenStack-docs] [RST] difference between the code and the code-block directive<br> </font> </div> <div class="y_msg_container"><br>Sometimes we use .. code:: and sometimes we use .. code-block::.<br><br>What is the difference? Does it makes sense to only use .. code-block:: <br>and to remove the usage of .. code::?<br><br>Christian.<br><br>-- <br>Christian Berendt<br>Cloud Solution Architect<br>Mail: <a ymailto="mailto:berendt@b1-systems.de" href="mailto:berendt@b1-systems.de">berendt@b1-systems.de</a><br><br>B1 Systems GmbH<br>Osterfeldstraße 7 / 85088 Vohburg / <a href="http://www.b1-systems.de/" target="_blank">http://www.b1-systems.de</a><br>GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537<br><br>_______________________________________________<br>OpenStack-docs mailing list<br><a ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br><br><br></div> </div> </div> </blockquote> </div></body></html>