Open Stack

On Mon, Mar 24, 2014 at 3:26 AM, Gauvain Pocentek <
gauvain.pocentek at objectif-libre.com> wrote:

> Le 2014-03-21 14:15, Anne Gentle a écrit :
>
>  On Fri, Mar 21, 2014 at 3:52 AM, Andreas Jaeger <aj at suse.com> wrote:
>>
>>  On 03/20/2014 09:37 PM, Diane Fleming wrote:
>>>
>>>> But I'm willing to go along with the consensus on this. And I totally
>>>> agree that we need to have one convention that we all use.
>>>>
>>>> But here's why I like two screens:
>>>>
>>>> 1. You can insert text between the user input and the computer output,
>>>> such an explanation of what the user might see in the output.
>>>>
>>>
>>> You still can do this, I see no problem with that.
>>>
>>
>> In the Ops Guide, we standardized on one screen wrapping <userinput>
>> and <computeroutput> but even so it was causing oddities with their
>> transforms.
>>
>> I'd prefer <screen> around each.
>>
>
> OK. So to sum up, we're (I'm?) not happy with our tools rendering when
> using multiple <screen>s, and we have rendering issues when using a single
> <screen> too, although this only concerns the ops guide. Did I understand
> correctly?
>
> Rendering set aside, I think that one screen is more logical, because you
> don't type the command in one terminal, and get the output in another one.
> And prompts explicitly define what is to be typed.
>
> To reuse an argument from the basic OS setup discussion that took place
> yesterday ([0]), we can probably assume that users know how to use the
> command line, and that they will understand what is to be typed and what is
> the output.
>

No, please don't use that argument again.

I was hoping a DocBook markup expert would give us guidance. I think that
semantically speaking, <screen> is meant to indicate all that someone sees
on a screen. To quote from the DocBook reference,

http://docbook.org/tdg5/en/html/screen.html

A screen <http://docbook.org/tdg5/en/html/screen.html> is a verbatim
environment for displaying text that the user might see on a computer
terminal. It is often used to display the results of a command.

Having less specific semantic overtones,
screen<http://docbook.org/tdg5/en/html/screen.html> is
often used wherever a verbatim presentation is desired, but the semantic of
programlisting <http://docbook.org/tdg5/en/html/programlisting.html> is
inappropriate.

>
> Let's try to move forward and make a decision about this, this shouldn't
> be that hard :)
>

It's hard because the semantics aren't specific. I am fine with a single
<screen> since that is what the user sees. I think we can make the output
nicer. Feel free to file a bug with the doc-builds tag for
openstack-manuals.

Thanks,
Anne




>
> Thanks,
> Gauvain
>
> [0]: http://lists.openstack.org/pipermail/openstack-docs/2014-
> March/004144.html
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140324/f5cc690b/attachment-0001.html>