First of all: The clerk is somewhat stupid - after all it's only a piece of software, and it thinks that humans are better with thinking. As a result it only understands simple commands, which must be given in a simple form. Don't expect it to understand our language.
Moreover, it puts all the trust it has in us humans - you know it's a bit stupid ;-) . It does what we tell it to do, regardless how wrong it may be. If someone asks it to delete an entry from the approval queue, it does it immediately. It executes all commands, which make any sense to it.
Only if there are real impossibilities (e.g. approving a mail which never appeared on list-raw), it disobeys the execution of this particular command, but continues with the next one.
Only when the clerk detects something, which is obviously wrong (e.g. a non-existing command), and in no circumstances it would make any sense, it acts different: It refuses to execute any of the commands given.
Though the clerk is bit simple-minded, it knows, that humans, when writing mails, tend to write down what they think and feel. Well, that's not interesting for the clerk. It's only interested in commands directed to it.
To help the clerk identifying the commands, which may be contained
in normal text, only lines starting with an exclamation mark (!)
are considered by the clerk. An exclamation mark as the first
non-white character (a non-white character is anything besides a space
or a tab in this case) in a line draws the attention of the clerk,
while it ignores all lines, which start with other characters.
Once aroused by an exclamation mark, the clerk looks for a command. The first word after the exclamation mark is considered being a keyword for the command. The word may be seperated by white-space from the exclamation mark, or may be concatenated right behind it.
Well, now for a very easy first example. I'm indenting examples by a tab so they can be found easier. The following may be the body of a post to list-work:
Subject: Re: (en) Project exploits a pure clerk
Hi orgers!
I think the post I'm replying to is pretty interesting. I like
to
! approve
it. Hope you won't mind.
Well, the clerk sees the line starting with the exclamation mark, scans and parses it, interprets it as a command, and executes it. The other lines are completly ignored by the clerk.
Instead of the format used above, one may have written any of the following:
!approve
! approve
! approve
!approve
The clerk uses white space always as a seperator, so it's usually ignored, and has no meaning besides seperating two words from each other. This is similar to human writing.
Words always must be seperated by an arbitrary amount of white space. Space and tab characters count as white space.
Thus the following lines contain the same words:
two words
two words
two words
two words
This line contains only one word:
twowords
while this contains three:
two wo rds
Besides this things can be quoted, and lines may be continued. This is described in detail in SYNTAX in the Language manpage and is usually not needed.
Some commands need something more to make sense. For instance if you want to change the language tag of a post, you need to give a new tag. Information given this way is known as an argument. Every word after the first one is an argument of it's own.
The number of arguments a command may take depend on the nature of the command. Moreover, arguments usually need a special form to be useful. For example a number may consist of digits only. This is known as a data type.
The number and type of arguments are described together with the command. For successful execution of a command the arguments given must match the data type and they must be valid.
Another example may show what this means. A replying post to list-work may read:
Subject: Re: Projekt beutet Clerk aus
Hi workers!
This post is definitely written in
! language de
In this example one advices the clerk to assume the referenced post
is written in certain language. The language (de) is given as an
argument.
Some commands may need some arguments only in special cases. These
arguments are called optional and may be omitted when the command
is given. In the description of a command such arguments are
surrounded by brackets ([]).
Some commands can take a unspecified number of arguments all at once.
This is known as a list of arguments. Lists of arguments are always
the last arguments of a command. In the following description such
arguments are followed by ellipsis (...), meaning that the argument
preceeding the ellipsis may be given once or more times.
If an argument list may be empty, the argument preceeding the ellipsis is optional.
Well, now you know something about the basic techniques to instruct the clerk, you may have a look at what you actually may want from it at the Command manpage.
If the Clerk detects errors of some sort, it generates a reply mail
starting with Er: to tell about the errors, which occured during
the execution of the command. It may look like this:
references:1:Having plain mail for '<message@id>' no more
Every error lists the command, which had the error (references),
the line number in the body of the mail, the logical command line
started (1), and a descriptive text, describing the nature of the
error.
The meaning of errors may be looked up in ERRORS in the Command manpage.