Open Stack

On 09/25/2015 05:29 PM, Matt Kassawara wrote:
> I think we can all agree that lowering the barrier to entry for
> potential contributors serves as one of the larger reasons for migrating
> from DocBook to Sphinx/RST. In addition to a rather complex build
> environment and rigid syntax, one could argue that the addition of
> custom semantic markup specific to our documentation made DocBook even
> more daunting for potential contributors. During the migration to
> Sphinx/RST, we somehow added semantic markup (e.g., :file:`file.conf`)
> that clouds an otherwise simple language already familiar to a
> significant number of potential contributors, particularly developers
> who we really need to keep our documentation fresh and useful.
> Furthermore, our semantic markup doesn't render any differently than
> standard Sphinx/RST (e.g., :file:`file.conf` vs. ``file.conf``). I
> propose that we eliminate our semantic markup and follow Sphinx/RST
> standards/conventions as much as possible.


What do you mean with custom here? Standard Sphinx has :file:, see
http://sphinx.readthedocs.org/en/latest/markup/inline.html?highlight=file#role-file

I agree that we should not invent our own semantic markup, but using the 
one from Sphinx is fine IMHO.

Andreas
-- 
  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
        HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126