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

Blockquotee markup

blockquote.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 mark-up

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.user {font-style: oblique ; color: #9400D3 }
Any system login name, from /etc/passwd. For example root, For example operator, or nobody.
code.group {font-style : oblique ; color: #FF0094 }
Any system group name, from /etc/group. For example kmem, staff, or nogroup.
code.package {font-style: italic; color:#666600 }
To highlight the name of a level 3 package or less often a level 2 product's package name.
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 rm -rf /usr as the superuser, which is not what we want to happen:
$ op dink /usr
em.new { color: #00cc33 }
The difference between a new example and the last one. For example:
$ ls /dev/nul
/dev/null
$ ls /dev/bull
ls: /dev/bull: No such file or directory
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 HTML documents.

Italic fill-in the blanks

I markup text that should be replaced or is a locally variable value as italic.
i.fillin {color: orange}
Text marked with orange italic markup is either a place to fill-in real data (usually marked as "%% clue %%"). The orange italic ellipsis ("...") denotes text that was obvious, or might confuse rcs or some other processor.
For example, we delete the tail of all example rcs keyword markup to prevent co from expanding the token to match the HTLM document's revision information and we denote meta-string replacement points with this markup.
# $Id: ...
# Meta-Makefile for %% product name %%, msrc 2008

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 their access with a strong password or cryptographic keys. A mortal login may provide services to others via setuid programs, network services, or other assets -- but that is wholly their responsibility.
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 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 used to denote a manual page, but no users are in that group. Many application logins have a group of adornment (spelled the same as the login) to secure their files from permissive 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.

If a mortal user's primary login group is used as a privileged group (as above), it is wholly on that person to secure their account. The admin's only role is to verify that the potential escalation was intended.



$Id: code.html,v 1.23 2013/10/01 16:52:33 ksb Exp $ by .