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 e.g. /opt/ instead.
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>KWrite</application> is the name of the editor, but <command>kwrite</command> is the name of the command that starts the KWrite application.
All KDE applications, and several non-KDE but very common applications, are provided as entities.
For the KDE 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, e.g. &kcontrol;, &konqueror; or &kmail;.
For non-KDE applications, one of the major reasons to use the entities is that there are legal implications, so far as we are required to acknoledge trademarks and copyrights held by others outside our organisation. You will find in Appendix A a list containing a list of the more common non-KDE application entities.
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.
Any text that the user must type, including commands and data entry.
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.
Text the user enters to instruct the computer or an application to do something. ls -al is a command (it's also userinput, and has options.) /join #kde 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.
The prompt at which a user types input. For most KDE Documentation, this has been standardised as <prompt>%</prompt> (which is the % character).
An optional parameter to a command. Since we write about UNIX® platforms, an option on the commandline is almost always indicated by a “-”, but there are exceptions (e.g., tar zxvf filename.tar.gz or ps ax, 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.
An environment variable. Note that the variable indicator (usually $ for UNIX®) is not part of the name of the environment variable, so it is correct to do this: $<envar>KDEDIR</envar>. There are no attributes in use in KDE Documentation.
A (usually numeric, but not always) error code. SIGSEGV is an errorcode, as is 404 as you might receive when you are web browsing.
The actual text of an error message - to reuse the 404 example, the <errorname> might be Page not found.
Use <filename> for all occurrences of file names including:
Do not use <filename> for file fragments or extensions (i.e. *.tgz which should instead be marked up as <literal role="extension">.
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 (e.g. <envar> or <constant> then you should use that instead.