ubuntu-developer-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

The ubuntu-manual style guide indicates different commands for various (but not 
all) widget types. For example tabs, buttons, check boxes, menus, windows.

 * Widgets almost all display in bold and are visually indistinguishable
 * Menus are bold and use path separators
 * Window's are put in double quotes. end up in the index.

Are all these format command necessary? I find boldfacing UI quotes as a single 
universal rule works well.

I also find the "menu path delimiters" more broadly useful that in *just* menus, 
for example, to include tabs and various widgets as needed.

Consider this path:
Edit > Preferences > Addressing (is a tab) > Don't Auto-Complete (is a checkbox)

Currently, this would be written like this:
\menu{Edit \then Preferences \then \tab{Address} \then \checkbox{Don't Auto 
Complete}

Consider these simplified the style guide rules/commands:
 * Bold text for quoted GUI bits (with textbf{something})
 * Provide a path delimiter, say: \path (or just use the greater than sign)

With these, the above would be written as follows:
\textbf{Edit} \path \textbf{Preferences} \path \textbf{Address} \path 
\textbf{Don't Auto Complete}

It is *longer*. But it doesn't require me to remember which source formats exist 
(tab, checkbox) and which don't (slider, radio button, etc).
In other words, it lowers the barrier for writers and simplifies source and .cls 
maintenance.

Regarding window titles, I doubt users will know that if it is quoted, it means 
a window,even if you state it in the book. I would do something like this;
"In the textbf{Graphics} window, do something."

I *do* find it useful to add (non-bold) widget-type words when helpful, so I 
would actually write the above like this:

\textbf{Edit} > \textbf{Preferences} > \textbf{Address} tab > \textbf{Don't Auto 
Complete} checkbox

And in context:
"
Disable address auto-completion:
\textbf{Edit} > \textbf{Preferences} > \textbf{Address} tab > \textbf{Don't Auto 
Complete} checkbox
"

See the attached.

Cheers,
Kyle

Attachment: widget-formats.png
Description: PNG image