Open Stack

On 05/02/2014 09:24 PM, Anne Gentle wrote:
>
>
>
> On Fri, May 2, 2014 at 2:16 PM, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
>
>     On 05/02/2014 07:53 PM, Anne Gentle wrote:
>
>         I looked up Rackspace style and for a list that provides terms
>         and more
>         information that is not meant to be marked up as a variable
>         list, it's:
>
>         term space emdash space definition phrase period
>
>         Example:
>
>            * *Public* – This setting allows any two servers with public IP
>
>              addresses to be load balanced. These can be nodes outside
>         of the
>              Rackspace network, but if they are, standard bandwidth
>         rates apply.
>
>
>         I'd like to have someone at RedHat look up their style guide and
>         let us
>         know.
>
>
>     For the Operations Guide, we used - as specified by O'Reilly's guide
>     - no spaces around the emdashes.
>
>
> Technical these examples ARE variable lists and O'Reilly's style wants
> it written as such.
> http://chimera.labs.oreilly.com/books/1230000000969/ch02.html#variable_list

I agree that they are indeed variable lists - but we haven't followed 
the markup usage in the manuals.

I'm fine with whatever convention we agree on, my goal is to have 
consistency for new text and changes.

> Frequently, bulleted lists should be converted to variable lists. Any
> bulleted list whose entries consist of a short term and its definition
> should be converted. For example, the following bulleted list entries:
>
>   * Spellchecking: process of correcting spelling
>   * Pagebreaking—process of breaking pages
>
> should be variable list entries:
>
> Spellchecking
>     Process of correcting spelling
> Pagebreaking
>     Process of breaking pages

So, these two reviews:
https://review.openstack.org/91736
https://review.openstack.org/90625

should get a -1 because of not using variable lists?

Do we agree on this convention? Then I'll make it a bit clearer in the 
conventions wiki page and will review accordingly.

>
>     What does the Rackspace guide say about the markup for term? Is it
>     emphasis in "bold"?
>
>
> No additional markup for the term.

That's different from what is used in many places in the manuals and if 
we go to variable lists, it is mood.

thanks,
Andreas

>
>
>         Ideally we'll be able to answer these if Rackspace or RedHat
>         gets their
>         style guide externalized so we can look it up.
>
>
>
>     Andreas
>
>         Thanks,
>         Anne
>
>
>         On Fri, May 2, 2014 at 2:03 AM, Andreas Jaeger <aj at suse.com
>         <mailto:aj at suse.com>
>         <mailto:aj at suse.com <mailto:aj at suse.com>>> wrote:
>
>              I've seen various forms used during reviews in lists with
>         many items:
>
>              1)
>              <listitem><para><guilabel>Boot from
>         image</guilabel>—If you choose
>              ...
>
>              2) And also:
>              <listitem>
>              <para><code>scheduler_filter_____classes</code> - Specifies
>         the list
>
>              of filter
>
>              And then the usage of
>              3) <formalpara> with <title>,
>
>              4) ":" instead of —,
>              5) &ndash or "-"
>
>              I've seen recently some patches using the first variant but
>         there's
>              a lot of variations. Do we want to have a consistent style
>         for new
>              changes? And which one?
>
>              This was triggered by reviewing
>         https://review.openstack.org/____91736
>         <https://review.openstack.org/__91736>
>              <https://review.openstack.org/__91736
>         <https://review.openstack.org/91736>>,
>         https://review.openstack.org/____90625
>         <https://review.openstack.org/__90625>
>
>              <https://review.openstack.org/__90625
>         <https://review.openstack.org/90625>> and then editing
>              config-reference/compute/____section_compute-cells.xml
>
>              Andreas
>              --
>                Andreas Jaeger aj@{suse.com <http://suse.com>
>         <http://suse.com>,opensuse.org <http://opensuse.org>
>              <http://opensuse.org>} Twitter/Identica: jaegerandi
>
>                 SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg,
>         Germany
>                  GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG
>              Nürnberg)
>                   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A
>         563C C272
>              A126
>
>              ___________________________________________________
>              Openstack-docs mailing list
>              Openstack-docs at lists.__opensta__ck.org <http://openstack.org>
>              <mailto:Openstack-docs at lists.__openstack.org
>         <mailto:Openstack-docs at lists.openstack.org>>
>         http://lists.openstack.org/____cgi-bin/mailman/listinfo/____openstack-docs
>         <http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs>
>
>         <http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs
>         <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>>
>
>
>
>
>     --
>       Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org
>     <http://opensuse.org>} Twitter/Identica: jaegerandi
>        SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>         GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG
>     Nürnberg)
>          GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272
>     A126
>
>     _________________________________________________
>     Openstack-docs mailing list
>     Openstack-docs at lists.__openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>
>     http://lists.openstack.org/__cgi-bin/mailman/listinfo/__openstack-docs
>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>
>


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