Open Stack

Doh, bad word choice. How about... lesser semantic markup that adds
complexity to the code without appreciable benefit to our audience in the
output.

On Fri, Sep 25, 2015 at 9:36 AM, Andreas Jaeger <aj at suse.com> wrote:

> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150925/f65d8d03/attachment.html>