Open Stack

One screen is fine – especially if the style of the output changes so that user can see the input versus the output.


Diane
----------------------------------------------
Diane Fleming
Software Developer II - US
diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com

From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Date: Monday, March 24, 2014 9:23 AM
To: Gauvain Pocentek <gauvain.pocentek at objectif-libre.com<mailto:gauvain.pocentek at objectif-libre.com>>
Cc: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>, openstack-docs <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
Subject: Re: [Openstack-docs] Convention on <screen> use




On Mon, Mar 24, 2014 at 9:20 AM, Gauvain Pocentek <gauvain.pocentek at objectif-libre.com<mailto:gauvain.pocentek at objectif-libre.com>> wrote:
Hey,

Thank you for your answer Anne.

Le 2014-03-24 14:18, Anne Gentle a écrit :

On Mon, Mar 24, 2014 at 3:26 AM, Gauvain Pocentek
<gauvain.pocentek at objectif-libre.com<mailto: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<mailto: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.

OK, this is certainly not the best argument I could have used. Sorry about that.
What I was trying to say was that we probably don't have to spell everything for the reader, and that using 1 screen makes things clear enough (in my humble opinion).

Please let me know if I'm completely out of line here, I'll just shut up :)

No worries at all, and I agree using one screen is probably clear enough that someone won't stumble into disaster areas. :) Thanks for logging the bug! Let's see what Diane thinks about the semantic markup here.



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 [1]

A screen [1] 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 [1] is often used

wherever a verbatim presentation is desired, but the semantic
of programlisting [2] 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.

Reported as https://bugs.launchpad.net/openstack-manuals/+bug/1296731

Gauvain

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140324/3db39144/attachment-0001.html>