Open Stack

On 11/11/2014 08:16 PM, Gauvain Pocentek wrote:
> Le 2014-11-11 15:21, Anne Gentle a écrit :
>> On Sat, Nov 8, 2014 at 12:51 PM, Andreas Jaeger <aj at suse.com> wrote:
>>
>>> As discussed on Friday at the Docpod, I'd like to add RST conventions so
>>> that they can be used by others, for example infra-manual.
>>>
>>> Looking at
>>> https://wiki.openstack.org/wiki/Documentation/Docbook_conventions [1] I
>>> propose to rename the page from "Docbook conventions" to "Markup
>>> conventions" and add for each Docbook example a corresponding RST
>>> example.
>>> I prefer this option (having Docbook and RST on the same page) since
>>> that also helps with moving from one to the other.
>>>
>>> Alternative would be a complete new page.
>>>
>>> Anybody with objections with moving forward with a single page?
>>
>> Ah, good thinking. So on that page, can we provide a mapping of
>> Docbook to RST? Such as:
>>
>> docbook=rst
>> command = :command:
>>
>> filename = :file:
>> literal = :samp:
>> programlisting = ?
>> screen = ?
> 
> I don't think we'll get as many tags in RST as we have in docbook. We
> can implement extensions in sphinx to add features, but this means more
> maintenance and it's probably not useful in most cases (Do we really
> need a <screen> equivalent?).

Still, we can document how to do it properly. The conventions page
explains which markup to use in which places and that's valid.

I would not go for further extensions at first step.

> Also, did we agree that RST is the way to go? I'm thinking PDF output
> here. Does it work well enough for us?

If we share the style guide with infra-manual, we should document it,

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