Re: interface tag

[Pat Costello <Patrick Costello Sun COM>]

Eric Baudais wrote: 

> Sasha-
> 
> My point is that you do not know if you will want the standard interface 
> terms altered by the stylesheets in any way.  Right now they aren't being 
> altered, but that could change in the future.  Maybe we wanted to have all 
> the interface terms added to links to a glossary by the appropriate 
> definition.  This could be done using a XSL stylesheet and would be hard to do
> any other way.  If all the standard interface terms were marked up adding 
> the link would be trivial with the stylesheet.
> 
> However, I do think there is a point where the documenter can mark up too 
> many words.  I'm not sure where this line can be drawn though.  Obviously 
> marking up GNOME and XML every time with the <acronym> tag is pointless, but 
> can the same be said for marking up standard interface terms.  My opinion is 
> these need to be marked up.
> 
> Eric Baudais


The information on the following TDG page clearly indicates that the <interface> 
tag is not current: 

http://www.oreilly.com/catalog/docbook/chapter/book/interface.html

Furthermore, the page advises authors to use an appropriate gui* tag instead of 
the interface tag. 

The proposal to tag every occurrence of all UI elements with the interface tag 
in order to allow for a UI elements glossary is, in fact, a new application for 
the interface tag. 

The suggestion to create a glossary of UI elements has some merit, however there 
is no need to employ blanket use of the obsoleted interface tag to do so. The 
tags firstterm and glossterm exist for this purpose.  However, the first 
occurrence only of a term need be tagged, not every occurrence. Even so, there 
is really only a need to employ this strategy in documentation that is aimed at 
educating the user about the desktop, and not in every item of user 
documentation, such as online Help for applets and applications. 

The assumption for application-specific online Help is that the audience has 
already learned enough about the desktop to recognise different elements. There 
is no more need to tutor people in fundamentals of the desktop environment, when 
they reach the stage of accessing online Help. Rather, a Help manual is about a 
particular application. Any generic desktop emphasis in these circumstances 
would be intrusive, and potentially confusing. If users need to find out 
something about the UI, then they can go to the top-level documentation, i.e. 
the user guide. 

At the desktop level, a glossary of less-known terms is already included in the 
user guide. This glossary does contain some of the UI elements. We could expand 
the glossary to include more UI elements, using the glossterm tag for the first 
instance. After the first instance, no more tagging would be required. 

Therefore, I have to conclude that the use of the interface tag is limited both 
in time and scope, and I see little point in advising GNOME authors to use this 
tag at all. 

Pat