openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

We just started a docs list for the openstack-doc-core team, with the
intent to discuss these conventions. So, I'm bringing them into the
discussion.

I appreciate all the explanation, and I'm agreeable to all these
conventions, as long as the rest of the team is okay with it. Thanks
for the explanation of <literal> it does have a better semantic
alignment to me for inline exact typing.

Thanks Russell! Unless I hear objections or further discussion by end
of day, I'll make these edits to the
http://wiki.openstack.org/Documentation/Conventions page so that it's
ready for Tuesday's Doc Day (otherwise I'd let us discuss longer but I
think that timing is critical here).

A few more comments embedded below to answer Russells' questions.
Thanks,
Anne

On Sun, Mar 4, 2012 at 3:15 AM, Russell Bryant <rbryant@xxxxxxxxxx> wrote:
> Hi, Anne.
>
> I'm not sure how wide the audience is for these comments.  If you think
> I should just re-post this to the main OpenStack list, let me know and I
> will do so.
>
> On 03/03/2012 11:56 PM, Anne Gentle (Code Review) wrote:
>> Anne Gentle has posted comments on this change.
>>
>> Change subject: Update docbook element usage.
>> ......................................................................
>>
>>
>> Patch Set 1: Looks good to me (core reviewer)
>>
>> Yeah, sure though I don't really know when to call something a literal - let's add guidance to http://wiki.openstack.org/Documentation/Conventions for what is a literal.
>
> I took a look at the conventions page.  Some of what I would use
> <literal> for conflicts with what is already on that page.  Here are the
> changes I would make.  Let me know which changes you are ok with and I
> will update the page.
>
>
> 1) "Information or configuration files that the user has to type or read"
>
> This uses <literallayout>.  I would propose using <programlisting>.

That's fine by me, though it'll take a while to change them all.

>
> 2) right command / wrong command
>
> There are a few instances where a "right command" and "wrong command"
> are referenced.  It appears that the '#' character is used with a wrong
> command.  It's not clear when this convention would be used.  Could you
> give me an example?
>
> I'm concerned that the use of '#' could be confusing since '#' is so
> commonly used as either a way to indicate that a command should be run
> as root or that any words after the '#' are a comment in a file.
>

Razique may have more explanation, we don't have many "wrong commands"
referenced but a way to indicate the "wrong way" to do something may
be helpful.

>
> 3) "Inline configuration information"
>
> I would use <literal> instead of <code> here.
>
> In general, I would use <literal> for any inline text that must be used
> exactly as typed.  In practice, this would usually be configuration
> options and configuration values.

Sounds good to me.

>
> 4) "Command to type into a specific shell"
>
> The current suggestion is to use:
>
>    <literallayout class="monospaced">
>    (mysql) command to type
>    </literallayout>
>
> I would write this as:
>
>    <screen>
>    <prompt>(mysql) </prompt><userinput>command to type</userinput>
>    </screen>

Ok this makes sense to me also.

>
> 5) "Result of the command"
>
> The current suggestion is to use <programlisting>.  I would use <screen>
> or <screen><computeroutput>.  So, a command combined with its output:
>
>    <screen>
>    <prompt>(mysql)</prompt> <userinput>command to type</userinput>
>    <computeroutput>result</computeroutput>
>    </screen>
Oh that looks helpful as well.
>
> 6) "File names"
>
> Instead of <literallayout>, <filename>
>
Okay. When we do this the output may not yet do anything to indicate
it is marked up but we'll need to find out.

>
> 7) Other
>
> Some other things I used in the doc updates I've done so far that I can
> add to the page:
>
> <command> - when talking about a literal command, like
> <command>nova-manage</command>
>
> <replaceable> - something used in combination with <literal>, when some
> part of the literal should be replaced by a user-specific value, like
> <literal>http://<replaceable>IP_ADDRESS</replaceable>/foo/bar</literal>
>
Yes, please do go ahead and add to the page. You can also edit it with
the items above as you see fit.
>
> Thanks,
>
> --
> Russell Bryant