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 <[email protected]> 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 -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
