use of non-breaking-spaces in manuals

[Roger Luethi]

I stumbled over non-breaking spaces in some odd locations. Most of
them are in the security-guide. Non-breaking spaces will print as a blank
but (unlike regular spaces) prevent line breaks in that location.
Non-breaking spaces in bad locations cause suboptimal line breaking.

In the example (from security-guide/ch051_vss-intro.xml) below, look for
<C2><A0>, the UTF-8 code for non-break spaces.

-----------------------------------------
<para>When evaluating base hypervisor technologies, consider if the
hypervisor has been certified against FIPS 140-2. Not only is conformance
against FIPS 140-2 mandated per U.S. Government policy, formal
certification indicates that a given implementation of a cryptographic
algorithm has been reviewed for conformance against module specification,
cryptographic module ports and interfaces; roles,<C2><A0>services, and
authentication; finite state model; physical security; operational
environment; cryptographic key management; electromagnetic
interference/electromagnetic compatibility (EMI/EMC);
self-tests;<C2><A0>design assurance; and mitigation of other
attacks.</para>
-----------------------------------------

To check XML documents for this issue, you can use GNU grep (note: this
will probably not work on a Mac, I think they switched to BSD grep):

export LESSCHARSET=ascii
grep -Pn --color=always '\xc2\xa0' *.xml|less

Maybe this is a well-known issue, but it's easy to overlook because many
editors and text viewers make it hard to recognize non-breaking spaces.

Use of non-breaking spaces in openstack-manuals:
      1 common
      2 image-guide
     34 security-guide
      1 user-guide-admin
     10 openstack-ops [ different repo ]

Some manuals use &nbsp; and define an XML entity for it (some manuals
even have both versions):
      4 admin-guide-cloud
      5 common
      1 glossary
      3 image-guide
      1 install-guide
      3 training-guides
      2 user-guide-admin
      1 user-guide

I suggest converting all non-breaking spaces to &nbsp; to make them easier
to spot and -- where appropriate -- remove (patch available).

I could also submit a patch that removes those instances that I consider
mistakes, but that would be a more subjective measure.

[Andreas Jaeger (jaegerandi)]

We document one usage for &nbsp; on the conventions page: Numbers and units, e.g. 1&nbsp;GB.

Patches are welcome - even ones that remove those instances that you consider mistakes.

[Openstack Gerrit (openstack-gerrit)]

Related fix proposed to branch: master
Review: https://review.openstack.org/91423

[Openstack Gerrit (openstack-gerrit)]

Reviewed: https://review.openstack.org/91420
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=063c3693f7f5080d8c00d57b652a95f2090ab503
Submitter: Jenkins
Branch: master

commit 063c3693f7f5080d8c00d57b652a95f2090ab503
Author: Roger Luethi <email address hidden>
Date: Wed Apr 30 18:55:36 2014 +0200

    Fix use of non-breaking-spaces in manuals

    Non-breaking spaces should only be used where necessary to
    prevent line breaks.

    This patch removes and replaces non-breaking spaces as appropriate.

    Closes-Bug: #1314498

    Change-Id: I43565603a8d0ff8672c23cfee049b04b612070f8

[Openstack Gerrit (openstack-gerrit)]

Reviewed: https://review.openstack.org/91423
Committed: https://git.openstack.org/cgit/openstack/openstack-doc-tools/commit/?id=930ddbac274d3a49623baf92c346d1c0f9f100b0
Submitter: Jenkins
Branch: master

commit 930ddbac274d3a49623baf92c346d1c0f9f100b0
Author: Andreas Jaeger <email address hidden>
Date: Wed Apr 30 19:39:17 2014 +0200

    Warn about usage of non-breaking space

    Non-breaking space is often not visible in our tools, or shown as normal
    space. We should use &nbsp; instead. Warn about non-breaking space like
    we warn about tabs.

    Change-Id: I1bbbb1f19c56d3cc1b949df151b41886a0c46042
    Related-Bug: #1314498

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/openstack-manuals 15.0.0 release.