Standard Syntax Musings

[Pasi Lallinaho]

Hey Jack (also sending this to the Xubuntu developer mailing list where 
issues like this can be worked on together),

The click/press -syntax you are proposing sounds good.

I believe that it is okay as long as we discriminate application names 
and probably button names from the text. While we might need to repeat 
"dialog" and "tab" in the text, it's not too often we will need to. With 
dialogs, it's usually OK as long as we tell the user to do something in 
the dialog that was opened. I haven't bumped in too many "tabs" in the 
documentation, but maybe we should reconsider this when we are reviewing 
the syntax some time next week.

At this stage, I think it is good enough if we can discriminate all 
these things under consideration from the normal text. If that's the 
case, it's easy enough to give them a special style, or not.

I'm not sure about field names: how many situations is there when we 
need to tell the user to fill in a specific field, not just everything 
in a dialog anyway?

I would not touch the font to make something stand out of the body text. 
The only exception to this is the command etc. stuff; this is because 1) 
terminals use monospace fonts by default 2) the user usually needs to 
copy the command exactly correctly, and a monospace font has less 
ambiguous characters.

Colors... Well, we can think about it, but I wouldn't use too many 
colors. The current DocBook style actually already uses a different 
style for application paths, which is blueish too.

Anybody else have ideas?

Pasi

On 01/09/12 20:15, Jack Fromm wrote:
> Pasi,
>
> Re the discussion we had the other night in the chat room, I had a 
> couple of thoughts.
>
> As for you question about "click" or "press" for buttons, I would 
> suggest that anything done with a mouse should be click and only 
> things done with the keyboard (e.g., Alt+F2) should use "press".
>
> Since this help file is not going to have any screenshots, I'm 
> wondering if we need a way to discriminate between buttons, 
> application names, dialog titles, tabs and field names.  It might make 
> things less confusing and prevent having to always specify in the text 
> which one of those things you are referring to. It looks like the 
> formatting options in the wiki are limited as to choice of fonts and 
> colors so if you did decide to make each of them unique, we'd have to 
> use a temporary format. But I would assume when you convert to Docbook 
> format, you would have many more options.
>
> Or not. :-) I know it's pretty late in the game.
>
> Jack


-- 
Pasi Lallinaho (knome)                      » http://open.knome.fi/
Leader of Shimmer Project and Xubuntu       » http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member  » http://xubuntu.org/