<div dir="ltr">Doh, bad word choice. How about... lesser semantic markup that adds complexity to the code without appreciable benefit to our audience in the output.</div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Sep 25, 2015 at 9:36 AM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">On 09/25/2015 05:29 PM, Matt Kassawara wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I think we can all agree that lowering the barrier to entry for<br>
potential contributors serves as one of the larger reasons for migrating<br>
from DocBook to Sphinx/RST. In addition to a rather complex build<br>
environment and rigid syntax, one could argue that the addition of<br>
custom semantic markup specific to our documentation made DocBook even<br>
more daunting for potential contributors. During the migration to<br>
Sphinx/RST, we somehow added semantic markup (e.g., :file:`file.conf`)<br>
that clouds an otherwise simple language already familiar to a<br>
significant number of potential contributors, particularly developers<br>
who we really need to keep our documentation fresh and useful.<br>
Furthermore, our semantic markup doesn't render any differently than<br>
standard Sphinx/RST (e.g., :file:`file.conf` vs. ``file.conf``). I<br>
propose that we eliminate our semantic markup and follow Sphinx/RST<br>
standards/conventions as much as possible.<br>
</blockquote>
<br>
<br></div></div>
What do you mean with custom here? Standard Sphinx has :file:, see<br>
<a href="http://sphinx.readthedocs.org/en/latest/markup/inline.html?highlight=file#role-file" rel="noreferrer" target="_blank">http://sphinx.readthedocs.org/en/latest/markup/inline.html?highlight=file#role-file</a><br>
<br>
I agree that we should not invent our own semantic markup, but using the one from Sphinx is fine IMHO.<span class="HOEnZb"><font color="#888888"><br>
<br>
Andreas<br>
-- <br>
 Andreas Jaeger aj@{<a href="http://suse.com" rel="noreferrer" target="_blank">suse.com</a>,<a href="http://opensuse.org" rel="noreferrer" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,<br>
       HRB 21284 (AG Nürnberg)<br>
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126<br>
<br>
</font></span></blockquote></div><br></div>