paragraph wrapping doesn't happen inside table cells

[Tom Fifield]

Long strings inside table cells, such as in http://docs.openstack.org/trunk/openstack-compute/admin/content/hypervisor-configuration-basics.html, cause the column of the table to be as wide as the long string. This is not ideal for reading.

[Denis Bradford (denisbatgm)]

I'll take ownership of this bug, if I'm approved before someone else beats me to it.

The PDF output is also unreadable: table column width is not expanded, but the long strings are compressed. I think our doc convention in such cases is to edit the source and force line breaks by either adding whitespace (if appropriate) or <?sbr?> processing instructions.

It would be nice to automatically wrap these long API names. That might work for PDF, for which hyphenation utilities are available. But I don't know of a way to wrap gracefully for the HTML output.

[Anne Gentle (annegentle)]

I think the doc convention is right for PDF, and I also don't know of a way
to make wrapping work for HTML. Thanks for picking it up!

On Wed, Jul 17, 2013 at 1:45 PM, Denis Bradford <email address hidden>wrote:

> I'll take ownership of this bug, if I'm approved before someone else
> beats me to it.
>
> The PDF output is also unreadable: table column width is not expanded,
> but the long strings are compressed. I think our doc convention in such
> cases is to edit the source and force line breaks by either adding
> whitespace (if appropriate) or <?sbr?> processing instructions.
>
> It would be nice to automatically wrap these long API names. That might
> work for PDF, for which hyphenation utilities are available. But I don't
> know of a way to wrap gracefully for the HTML output.
>
> --
> You received this bug notification because you are subscribed to
> OpenStack.
> https://bugs.launchpad.net/bugs/1196187
>
> Title:
> paragraph wrapping doesn't happen inside table cells
>
> Status in OpenStack Manuals:
> Confirmed
>
> Bug description:
> Long strings inside table cells, such as in
> http://docs.openstack.org/trunk/openstack-compute/admin/content
> /hypervisor-configuration-basics.html, cause the column of the table
> to be as wide as the long string. This is not ideal for reading.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/openstack-manuals/+bug/1196187/+subscriptions
>

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/37906

[Denis Bradford (denisbatgm)]

The fix I proposed is apparently incorrect. According to review comments, these tables are automatically generated and changes like this will be overwritten next time the script is run. (The code that produces them can be found in https://review.openstack.org/#/c/35726/). Investigating how (and who) to fix the code generation...

[Denis Bradford (denisbatgm)]

Abandoned review per Anne. Setting this bug to incomplete and disowning it, because it's a bug in the code generation, not editable docs. In email, Tom Fifield has indicated he's open to a patch to the code generation. It might also help to include an SGML comment at the top of the generated file, something like <!-- this file is generated, not to be edited manually -->.

[Anne Gentle (annegentle)]

As long as the bug has "doc-builds" as a tag, I'm okay with calling the bug Confirmed. You okay with that Denis?

Also, https://review.openstack.org/#/c/35726/ does contain the comment code embedded in each table.

[Denis Bradford (denisbatgm)]

Okay with me!

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/63598

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/63598
Committed: https://git.openstack.org/cgit/openstack/openstack-doc-tools/commit/?id=6708afbef1f4a662fd1b164ce3f635ad71ba7662
Submitter: Jenkins
Branch: master

commit 6708afbef1f4a662fd1b164ce3f635ad71ba7662
Author: Andreas Jaeger <email address hidden>
Date: Sat Dec 21 22:38:15 2013 +0100

    Autogenerate config tools: Allow line wrapping

    The options have previously been written as "option=default". Let's
    add spaces like "opt = default" to allow line wrapping.

    Change-Id: Ie1fa1161adfb289feaf0d4bf801866a2dded5cd8
    Closes-Bug: #1196187