Possibly stupid question...

Karsten Wade kwade at redhat.com
Mon Aug 30 22:22:41 UTC 2004


On Sun, 2004-08-29 at 11:27, 'D at 7@k|N&' wrote:
> Since I have been working on the hardening tute, I've been doing so with
> the Docs Guide open, so I have an immediate reference for the tags that
> I should be using.  I noticed something, that other people may have
> noticed, but I don't really understand the point of.  The
> <guibutton></guibutton>, <guilabel>, <guimenu>, <guimenuitem>,
> <application>, and several other tags, all seem to just make the text
> bold.  Is there a reason that these aren't more defined?  (Something
> really could would be to id the guimenu buttons, and have the tag insert
> the graphic for that button, etc.)  Without the more differentiating
> characteristics, what is the point of using different tags?

/me is kind-of repeating what Paul said, but ...

The styling (bold, etc.) is in the stylesheets, and has no meaning to us
on the markup side.

The markup should be contextual, only.  We never do things so that they
"look" a certain way in one of the many ways to render a document.  
This lets us focus on the content and not the formatting, and the
separation of the layers lets us have more global control.  We want all
<guibutton/> tags to now make a button-like appearance using CSS in
HTML, but not PDF, we can do that in the XSL and the CSS.

The button-effect was done in Red Hat manuals in the past, and we could
do that if it was worth it.

Here's an example to illustrate the value of proper content tagging and
not worrying about the presentation:

You are writing a tutorial for using GTK+ to create some onscreen
widgets.  It includes <programlisting> blocks with lots of sample code,
some <screen> blocks with commands for installing packages and tweaking
configuration files, and several textual descriptions of a GUI, talking
about the <guibutton>s, <guilabel>s, and <guimenu>s.

One of your readers is very visually impaired.  She has to use two huge
monitors set at 640x480 with large fonts and contrasting colors, and has
both a regular and Braille keyboard, and a Braille printer for output.

If your content was marked up with enough proper detail, an XSLT could
be used to get the XML ready for a custom low-vision reading system that
would:

* Take the <programlisting> blocks and send them intact to the reader's
monitor and Braille output printer (both configured to receive STDOUT);
this lets her see them on screen and confirm what she reads with Braille
output.

* Take the <gui...> elements and display them in a properly nested
fashion to STDOUT, similar to the way they give us File -> Edit -> Foo,
that could be a visually descending tree done in a very big font.

* Take the <screen> and <computeroutput> tags and send that content
straight to the console and Braille keyboard (STDIN), while teeing it to
STDOUT for confirmation via monitor and Braille printer.

Does that help?

- Karsten


-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41





More information about the fedora-docs-list mailing list