yahoo-eng-team team mailing list archive

[Brian Rosmaita <rosmaita.fossdev@xxxxxxxxx>]

Public bug reported:

This applies to the files in doc/source/cli

The options are marked up as a definition list, with the options in
bold, for example:

  **-o, --option**
    This is an option.

  **-a, --another**
    This is another option.

This is a problem because when the document is rendered into HTML by
Sphinx, '--' is converted into a single character, 0x2013 (en dash)
instead of remaining as two consecutive hyphens.  This is confusing to
readers.

The options should instead be marked up as an option list:

  -o, --option  This is an option.
  -a, --another  This is another option.

There must be at least 2 spaces between the option and the description.
The options will be rendered in monospace font and the two hyphens are
preserved.

See http://docutils.sourceforge.net/docs/user/rst/quickref.html#option-
lists

** Affects: glance
     Importance: Low
         Status: Triaged


** Tags: documentation

** Tags added: documentation

** Changed in: glance
       Status: New => Triaged

** Changed in: glance
   Importance: Undecided => Low

-- 
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to Glance.
https://bugs.launchpad.net/bugs/1743040

Title:
  incorrect ReST markup in CLI documentation

Status in Glance:
  Triaged

Bug description:
  This applies to the files in doc/source/cli

  The options are marked up as a definition list, with the options in
  bold, for example:

    **-o, --option**
      This is an option.

    **-a, --another**
      This is another option.

  This is a problem because when the document is rendered into HTML by
  Sphinx, '--' is converted into a single character, 0x2013 (en dash)
  instead of remaining as two consecutive hyphens.  This is confusing to
  readers.

  The options should instead be marked up as an option list:

    -o, --option  This is an option.
    -a, --another  This is another option.

  There must be at least 2 spaces between the option and the
  description.  The options will be rendered in monospace font and the
  two hyphens are preserved.

  See http://docutils.sourceforge.net/docs/user/rst/quickref.html
  #option-lists

To manage notifications about this bug go to:
https://bugs.launchpad.net/glance/+bug/1743040/+subscriptions