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 ksb.