These are the mark-ups I use to help make the documentation for all my tools easier to read.

Code mark-up

code.file {background-color: #cccc00}
A section of code that comes from a file renders as a block element as:

# This is an example comment in a file mark-up
And this would be a line of code in the example file.
code.attr {color: #EE00EE }
I have several features a call "attributes". These are all marked-up with this class. Usually an attribute is a macro of some kind (m4, or some processor I wrote) and is marked-up in-line. For example an attribute named "HUE" would look like HUE.
code.sh {color: #00DD00 }
A shell command might be taken for an English word, if it were not identified with mark-up. For example the shell command "halt" is written as halt.
code.opt {color: #0000DD }
A command line option to a shell command is given as -o.
code.param {font-style: italic}
A parameter to a shell program is given as param. This is the same markup used to an option specification, for example make's recipe file under -f is given as makefile.
code.make {color: #DD0000 }
I use a lot of make recipe files, so I've had to give the macros in a makefile special markup. The common "CFLAGS" macro is given as CFLAGS.
code.env {color: #00CCCC }
To show the difference between make's macros and shell environment variables we mark the latter with a different markup. The "PATH" environment variable is marked as PATH.
code.libc {font-style: italic ; color: #CCCC00 }
Some library functions and system calls might be mistaken for English works without markup. For example the "shutdown" system call is marked as shutdown.
code.path { text-decoration: underline }
A path through the filesystem may be marked as /dev/null. This is not always included, when it is clear that every element in a list must be a filename.
code.rdist {color: #CCCC00 }
Like make's makefile, rdist's distfile contains macros that might be mistaken for shell variables. I mark these with INTO.
code.markup {font-style: italic ; color: #00CC66 }
To explain any other markup I would use the general purpose class "markup". For example to explain the use of the commercial at sign in a scp target.
The commercial at (@) is placed between the user and host parameters as user@host.

Emphasis

I limit the use of emphasis to really dangerous errors, for example commands that would destroy data (which one would never execute), and to new text in an old document while my proof readers are still reviewing the draft.
em.error { color: red }
Text that is a never-type example. For example:
This would run sudo rm -rf /usr, which is not what we want to happen.
em.new { color: #00cc33 }
Updates that I want a proof reader to comment on. This is the new example.

$Id: code.html,v 1.4 2010/08/13 17:33:34 ksb Exp $