DocBook tags <screen> and <userinput> remove <step> letter/number

[Everett Toews]

Using the DocBook tags <screen> and <userinput> remove <step> letter/number from the output.

http://imgur.com/4DeLT4C

Note the lack of substep a. or d.

This was produced by the markup

<step>
    <para>Login and set up DevStack.</para>
    <substeps>
        <step>
            <screen><userinput>ssh <email address hidden>
            </userinput></screen>
        </step>
        <step>
            <para>
                <code>sudo apt-get -y update</code>
            </para>
        </step>
        <step>
            <para>
                <code>sudo apt-get -y install git</code>
            </para>
        </step>
        <step>
            <screen><userinput>git clone https://github.com/openstack-dev/devstack.git -b stable/havana devstack/
            </userinput></screen>
        </step>
        ...
    </substeps>
<step>

[David Cramer (david-thingbag)]

I'm not able to reproduce this by pasting the above markup into a test document. Could you point me to an existing document where it happens?

[Anne Gentle (annegentle)]

Sure, it's in the master branch of the openstack/operations-guide repo.

On Sat, Jan 25, 2014 at 4:12 PM, David Cramer <email address hidden>wrote:

> I'm not able to reproduce this by pasting the above markup into a test
> document. Could you point me to an existing document where it happens?
>
> --
> You received this bug notification because you are subscribed to
> OpenStack.
> https://bugs.launchpad.net/bugs/1272369
>
> Title:
> DocBook tags <screen> and <userinput> remove <step> letter/number
>
> Status in OpenStack Manuals:
> New
>
> Bug description:
> Using the DocBook tags <screen> and <userinput> remove <step>
> letter/number from the output.
>
> http://imgur.com/4DeLT4C
>
> Note the lack of substep a. or d.
>
> This was produced by the markup
>
> <step>
> <para>Login and set up DevStack.</para>
> <substeps>
> <step>
> <screen><userinput>ssh <email address hidden>
> </userinput></screen>
> </step>
> <step>
> <para>
> <code>sudo apt-get -y update</code>
> </para>
> </step>
> <step>
> <para>
> <code>sudo apt-get -y install git</code>
> </para>
> </step>
> <step>
> <screen><userinput>git clone
> https://github.com/openstack-dev/devstack.git -b stable/havana devstack/
> </userinput></screen>
> </step>
> ...
> </substeps>
> <step>
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/openstack-manuals/+bug/1272369/+subscriptions
>

[David Cramer (david-thingbag)]

Ok, so this affects Chrome (and I suspect Safari). The rule "overflow-x: scroll;" on pre.screen (which adds the scroll bar) is causing it. I'm not sure what to do to avoid the problem though. I'll try to find someone wise in the ways of css to ask.

[David Cramer (david-thingbag)]

Here's a workaround that should work. Instead of this:

        <step>
            <screen><userinput>ssh <email address hidden>
            </userinput></screen>
        </step>

Do:

        <step>
           <para> <screen><userinput>ssh <email address hidden>
            </userinput></screen></para>
        </step>

I'll look into doing that programmatically.

[David Cramer (david-thingbag)]

Tip for fixing this: Best fix would be to figure out a css change to handle the situation (really this is a browser bug/limitation in certain browsers). If that's not possible, we could write some xslt that looked for steps that have a screen child and no other children and add a para in that case.

[Tom Fifield (fifieldt)]

Hi Chandan,

Are you still working on this?

[Anne Gentle (annegentle)]

Moving the <para> outside of <screen> fixes this issue. However, our current Conventions example shows <para> separately closed from <screen> https://wiki.openstack.org/wiki/Documentation/DocBook_conventions#Procedure

So I'm submitting a fix and will edit the wiki page as well, hopefully reviewers will alert if there's a separate issue with enveloping <screen> in with the <para>.

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/119137
Committed: https://git.openstack.org/cgit/openstack/operations-guide/commit/?id=7d9f8e17a158971d5b90e5af897970b6abed25db
Submitter: Jenkins
Branch: master

commit 7d9f8e17a158971d5b90e5af897970b6abed25db
Author: Anne Gentle <email address hidden>
Date: Thu Sep 4 12:41:14 2014 -0500

    Fixes missing substep alphanumeration in Customize

    Change-Id: I723739949b9da073d0ba2f0bb517f46ef8b1d90e
    Closes-bug: 1272369