Standard Syntax Musings
pasi at shimmerproject.org
Sat Sep 1 18:31:19 UTC 2012
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
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?
On 01/09/12 20:15, Jack Fromm wrote:
> 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.
Pasi Lallinaho (knome) » http://open.knome.fi/
Leader of Shimmer Project and Xubuntu » http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member » http://xubuntu.org/
More information about the xubuntu-devel