<replaceable>
Use this for placeholder or sample text, that a user would not
actually type, but would instead replace with the correct text for
their environment. For example, Edit the file
<filename><replaceable>/usr/local/foo/bar</replaceable></filename>,
because it may already be established that /usr/local
is only the default location
of this file, and the user may have it installed to for example, /opt/
instead.
<application>
Use this to mark up the name of any software program mentioned in the
text. Don't use this to mark up the actual command issued to execute
the application. For example, <application>Kate</application>
is the
name of the editor, but <command>kate</command>
is the name of
the command that starts the Kate
application.
All TDE applications, and several non-TDE but very common applications, are provided as entities.
For the TDE applications, using the entities will save you much
typing, and will ensure that applications are always referred to with
their correct name across all documentation. The entity is always the
application's executable name, in lower case, for example, &kcontrol;
, &konqueror;
or &kmail;
.
For non-TDE applications, one of the major reasons to use the entities is that there are legal implications, so far as we are required to acknowledge trademarks and copyrights held by others outside our organisation. You will find in Appendix A, Entities a list containing a list of the more common non-TDE application entities.
<interface>
Catch all element for gui interface items that do not have a more specific tag. You can use this to markup things like the “View pane” in KHelpCenter, or the “Board” in KJumpingCube.
<userinput>
Any text that the user must type, including commands and data entry.
<screen>
Used to represent the computer screen (usually to represent a terminal
or console.) Text contained in <screen>
is considered to be literal text —
line breaks and white space are honored and it will be rendered with a
mono-spaced font. Don't use screen when what you really want is an
example, or an informal example.
<command>
Text the user enters to instruct the computer or an application
to do something. ls
is a command (it's also userinput,
and has options.) -al
/join #tde
in an irc client is a command (and again, is
userinput.)
Commands are not userinput
when you
are not expecting the user to actually type them, for example in the
sentence “The output from the ls command should
show you...”, the text “ls” is a command, but is not
userinput
in this context.
Applications not marked up with the <application>
tag are also considered commands,
for example, gcc, automake and
autoconf.
<prompt>
The prompt at which a user types input. For most TDE
Documentation, this has been standardised as
<prompt>
%
</prompt>
(which is the % character).
<option>
An optional parameter to a command. Since we write about Unix-like
platforms, an option on the commandline is almost always indicated by a
“-”, but there are exceptions (for example,,
tar
or
zxvf
filename.tar.gz
ps
, which
are marked up as
<userinput><command>tar</command>
<option>zxvf</option>
<replaceable>filename.tar.gz</replaceable></userinput>
and <userinput><command>ps</command>
<option>ax</option></userinput> respectively.
ax
<envar>
An environment variable. Note that the variable indicator (usually $ for Unix-like) is not part of the name of the environment variable, so it is correct to do this: $<envar>TDEDIR</envar>. There are no attributes in use in TDE Documentation.
<errorcode>
A (usually numeric, but not always) error code. SIGSEGV is an errorcode, as is 404 as you might receive when you are web browsing.
<errorname>
The actual text of an error message - to reuse the
404 example, the <errorname>
might be Page not
found.
<errortype>
The type of error, for example, fatal or recoverable.
<filename>
Use <filename>
for all occurrences of
file names including:
Directory names — with the attribute class="directory"
Paths
File names
File name placeholders (which should also be tagged with
<replaceable>
Do not use <filename>
for file
fragments or extensions (that is, *.tgz
which should instead be marked up as <literal role="extension">
.
<symbol>
Symbols are things that are replaced by the computer when they are
processed. It's difficult to say when things are a symbol and when they
are not - if there is a more specific element to use (for example, <envar>
or <constant>
then you should use that instead.
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team