Standard Syntax Musings

[Jack Fromm]

<<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?>>
You may be right about that.  The only section where I can remember 
encountering them was Users and Groups.  BTW, it looks like that section 
and many others need to be edited again because apparently the latest 
Quantal release has moved things around in the menu hierarchy.

Jack

On 09/01/2012 02:31 PM, Pasi Lallinaho wrote:
> 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
>
>