Open Stack

On Mon, Mar 24, 2014 at 9:20 AM, Gauvain Pocentek <
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> 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.
>>
>
> 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/58ad6779/attachment.html>