The mark-up used in my HTML documents

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: #EEEEEE}

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: #00CC00 }

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 or option specification to a shell program named "param" is given as param. This is the same markup used for an option specification. For example, make's recipe file under -f is given as makefile.

code.make {color: #FF0000 }

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: #00EEEE }

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: #CC33CC }

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 {font-style: italic ; color: #0088EE }

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: #006666 }

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.
em.b { font-weight:bold }
em.i { font-style:italic }
em.bi { font-weight:bold ; font-style:italic }: These are only used to mock the output of the manpage.cgi script in HTLM documents.

Terms for roles

These are subtle differences in meaning that I use when a write about UNIX™ or similar systems. I define them here so I can be more clear with my explanations.

the superuser: The superuser is not a person, it is the special power given to uid 0, usually the login "root" has that special power.
the admin or administrator: A mortal login that can gain superuser power as needed, but doesn't always have uid 0. Such a person is responsible for installing software, configuring system files, and granting trusted users certain privileged operations.
a mortal user or mortal login: A common login bound to a person. That person is responsible for securing his access with a strong password and/or cryptographic keys.
an application login: An account that usually doesn't have a password or any interactive access by a person. Such an account is used to partition the application's actions from other application and/or mortal users.
a login of adornment
the adorning login: The adornment login is a variant of an application login, but applies when there is not really an "application" that runs as the login, only files owned by the login. For example, the "bin" or "adm" logins on some systems only serve to denote the purpose of each directory, they really don't grant special access to any applications.
a group of privilege: Membership in this group grants some extra access on behalf of a user, usually via a setuid program. For example group "wheel" (or "root") may be required to su to the superuser. The op privilege escalation program uses group membership to implement privilege access methods.
an access group: A group that is used to grant write (read) access to shared working files. For example group "source" is often used to grant commit access to the master source. Usually granting execute access to a file makes the group a group of privilege, while execute access to a directory doesn't imply that.
a group of adornment
the adorning group: A group with zero (or few) members that is used to exclude a file from having any group access by mortal or application users. For example the common group "man" is user to denote a manual page, but no users are in that group. Some application logins have a group of adornment (spelled the same as the login) to secure their files from accidental group access.

There is a fine line between an access group and an adornment. If the intent is to allow limited access then it is an access group. If the intent is to give every other login equal access (none or any other equal access), then it is only adornment.

If the default umask set for a site allows group write (viz. 002 rather than 022) then every personal login group is an access group. When a given login provides setgid services it becomes a group of privilege. It also becomes privileged when it allows op (or sudo) access to any escalation rules.

It is a good site policy to give mortal logins a personal group (usually named for the login name). It is a poor site policy to allow those groups to accidentally become groups of privilege. It may be hard to check for all the privilege cases, but a check through op's -r output and a few find checks are good start.

$Id: code.html,v 1.14 2012/03/27 16:49:57 ksb Exp $