The K Desktop Environment

3.8. Describing the Application's Interface

3.8.1. Examples

These are the tags covered in this section:
LiteralLayout - Wrapper for lines set off from the main text that are not tagged as Screens, Examples, or ProgramListing, in which line breaks and leading white space are to be regarded as significant
Example - Example of a computer program or related information
InformalExample - Untitled Example
ProgramListing - Listing of all or part of a program
Screen - Text that a user sees or might see on a computer screen

There are many situations where you must include examples of source code, commands, or GUI actions in your documentation. DocBook has many tags to support these needs. Whenever you want to include examples in your document, just put an <Example> or <InformalExample> tag around the example text or graphic.


Example 3-14. Example of an Example

 <example>
 <title>A BASIC Example</title>
 <programlisting>
 10 PRINT "HELLO WORLD"
 20 GOTO 10
 </programlisting>
 </example>
  

In this first example, we have a listing of a simple BASIC program. The code contained in the <ProgramListing> tag is displayed with the spacing and line breaks intact which is very useful for code examples and similar situations where you must preserve the literal formatting. The LiteralLayout and Screen tags work in the same way, but are used to indicate different types of content. Screen contains output that would appear on the screen, while LiteralLayout is used for any other text that must be rendered with line breaks and tabs.

The example would look something like this when converted to HTML:


Example 3-15. A BASIC Example

   1 10 PRINT "HELLO WORLD"
   2 20 GOTO 10

One problem can occur with the LiteralLayout, ProgramListing, and Screen tags: all text is rendered literally, but DocBook tags are still interpreted as tags and not text. What do you do when you need to show text without having your tags interpreted? The answer is to use <![ CDATA [ ]]>, which labels the text contained within the inner brackets as character data that should not be interpreted by the SGML parser. Any text within the brackets will remain as-is after the conversion, so the example above will successfully reproduce its tags.


Example 3-16. Example of a Markup Example

 <example>
 <title>A Markup Example</title>
 <screen> 
 <![ CDATA [
 <Para>This is a DocBook example.</Para>
  ]]>
 </screen>
 </example>
  

This is what the markup example would look like when converted to HTML:


Example 3-17. A Markup Example

 <para>This is a paragraph.</para> 

3.8.2. Command Line

The following tags are used to label elements of a command:
Type - Classification of a value
Literal - Literal string, used in-line, that is part of data in a computer
UserInput - Data entered by the user
Symbol - Name that is replaced by a value before processing
Replaceable - Content that may be replaced in a synopsis or command line
Filename - Name of a file, possibly including pathname
Prompt - Character indicating the start of an input field in a computer display.
ParamDef - Data type information and the name of the Parameter this information applies to
Parameter - Part of an instruction to a computer
Option - Option for a computer program command
EnVar - Environmental variable
Command - Executable program, or the entry a user makes to execute a command
CmdSynopsis - Synopsis for a Command
Arg - Argument in a CmdSynopsis
ComputerOutput - Data presented to the user by a computer

There are two situations in which you want to describe a command: showing an example of a command typed on the command line and a detailed description of all of the arguments and options to a command like you would see in a man page.

DocBook supports both of these contexts with the <Command> and <CmdSynopsis> tags.


Example 3-18. A Command and its Output

 <screen>
 <prompt>bash$</prompt> <command>twiddle <replaceable>myfile</replaceable>
 </command>
 twiddling myfile.....done!
 </screen> 

Would appear as:
 bash$ twiddle -c 1 myfile
 twiddling myfile.....done!

The command tag can also be used within a paragraph to mark the name of a command. For example:


 The <command>twiddle</command> command is used to twiddle
 files. Twiddled files will be marked with the .twid extension, so if I <command>twiddle</command>
 <replaceable>myfile</replaceable> then it will become
 <replaceable>myfile.twid</replaceable>. Errors are written to the
 file <filename>twiddle.err</filename>. 

The twiddle command is used to twiddle files. Twiddled files will be marked with the .twid extension, so if I twiddle myfile then it will become myfile.twid. Errors are written to the file twiddle.err.

The <Prompt> tag is simply used to label the prompt in a command line. Replaceable labels text that should be replaced by the user. In the example, myfile is just an arbitrary name for a file since we don't know and don't care what the name of the file is, we just want to show how the command is used. If a filename in a command is known, use the <Filename> tag instead.

Marking up a CmdSynopsis is a bit more difficult. Here is an example from the DocBook Reference:


Example 3-19. Foo Command Synopsis

 <cmdsynopsis>
    <!-- This is a synopsis for the command foo.
         The options -a and -x are optional and exclusive
         The option -c takes a cheese and is optional and repeatable
         The options -t and -k are referred to in another fragment
         The options -i, -j, and -k are required and exclusive
         The option -f takes a filename and is required
         The -t and -k options specify the kind of milk and mold in an
             optional and repeatable group
    -->
    <command>foo</command>
    <group>
      <arg>-a</arg>
      <arg>-x</arg>
    </group>
    <group>
    <arg rep="repeat">-c <replaceable>cheese</replaceable></arg>
    <synopfragmentref linkend="cheesetype">cheesetype</synopfragmentref>
    </group>
    <group choice="req">
      <arg>-i</arg>
      <arg>-j</arg>
      <arg>-k</arg>
    </group>
    <arg choice="req">-f <replaceable>filename</replaceable></arg>
    <synopfragment id="cheesetype">
      <group rep="repeat">
         <arg>-t <replaceable>milk</replaceable></arg>
         <arg>-k <replaceable>mold</replaceable></arg>
      </group>
    </synopfragment>
  </cmdsynopsis>
  

Which looks like this:

foo [-a | -x] [-c cheese(1)cheesetype] {-i | -j | -k} {-f filename}

(1) [-t milk | -k mold...]

A CmdSynopsis contains one Command, Groups of related Args, independent Args, and SynopFragments. The <Arg> labels arguments to the command. Arg has two attributes: choice and rep. Choice is used to indicate whether the tag is optional (the default), required (req), or to be displayed without any decoration (plain). The <Group> tag is used to group together related Args. SynopFragment is the most complicated of the CmdSynopsis tags. It is used to provide a more detailed description of options for an argument. A SynopFragment consists of two parts: the SynopFragment, which contains the additional Args, and the SynopFragmentRef which points to the detailed description.

3.8.3. GUI Interface Elements

Accel - Keycap used with a meta key to activate a graphical user interface
KeyCap - Text printed on a physical key on a computer keyboard, not necessarily the same thing as a KeyCode
KeyCode - Computer's numeric designation of a key on a computer keyboard
KeyCombo - Combination of input actions
KeySym - Key symbol name, which is not necessarily the same thing as a Keycap
MenuChoice - Menu selection or series of such selections
MouseButton - Conventional name of a mouse button
Interface - Element of a graphical user interface
InterfaceDefinition - Full or short name of a formal specification of a graphical user interface
GUIButton - Text on a button in a graphical user interface
GUIIcon - Graphic and, or, text appearing as a icon in a graphical user interface
GUILabel - Text in a graphical user interface
GUIMenu - Name of a menu in a graphical user interface
GUIMenuItem - Name of a terminal menu item in a graphical user interface
GUISubmenu - Name of a submenu in a graphical user interface
Action - Function invoked in response to a user event

One could almost say that there are too many tags in DocBook for describing GUI elements. Most of the tags listed above can be used in a variety of contexts, but a few, such as <KeyCap>, must be used within other tags. The example and explanation below will not cover all of the tags listed above. This list is for your convenience since the DocBook Reference does not group tags by their function.

All of the GUI tags can be used within the context of a regular paragraph. So if I wanted to talk about the Trash icon or the Empty Trash button, I would just use the <GUIIcon> and <GUIButton> tags like this: <GUIIcon>Trash</GUIIcon> icon, <GUIButton>Empty Trash</GUIButton> button. Note that all GUI tags may also contain inline graphics.

Below is a more complicated example of GUI tag usage from the template.


Example 3-20. GUIMenu and Shortcut example

 <variablelist>
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>New</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Creates a new document</action></para></listitem>
 </varlistentry>
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>Save</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Saves the document</action></para></listitem>
 </varlistentry>
 <varlistentry>
 <term><menuchoice>
 <shortcut>
 <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
 </shortcut>
 <guimenu>File</guimenu>
 <guimenuitem>Quit</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Quits <application>Kapp</application></action></para></listitem>
 </varlistentry>
 </variablelist>
  

I hope your eyes haven't glazed over at the sight of all those tags! The most complicated part of this example is the <Shortcut> tag which labels keyboard shortcuts for menuitems. Shortcut contains either a KeyCombo or a single KeyCap that contains the key or group of keys the use would press to invoke that menuitem from the keyboard. It is important to use the KeyCombo and KeyCap tags within the Shortcut tag because it is incorrect to use character data (the Ctrl-q text for example) within a Shortcut.

Other tags worth mentioning from the example are MenuChoice, Action, and Application. MenuChoice labels a menu choice and should contain the Shortcut (if any) the name of the menu in GUIMenu, and the name of the menuitem in GUIMenuItem. Action simply labels a phrase that describes what the menuitem (or other interface element) does. Application is a tag used to label the names of Applications.

The example would look something like this when converted to HTML:

File->New (Ctrl-n)

Creates a new document

File->Save (Ctrl-s)

Saves the document

File->Quit (Ctrl-q)

Quits Kapp