Begin documentation update

This update converts the documentation from the cursory Markdown in the
README.md file, and converts it into a typeset document, using Groff and
the MS macro package.

Currently, almost all of the existing documentation has been typeset,
and soon, I will work on continuing from where I had left off.

1 files changed, 258 insertions, 0 deletions

diff --git a/clformat/docs/clformat.ms b/clformat/docs/clformat.ms
new file mode 100644
index 0000000..9a36f63
--- /dev/null
+++ b/clformat/docs/clformat.ms
@@ -0,0 +1,258 @@
+\# CLFormat documentation
+\# Useful macros
+\# Section header
+.de Section
+.NH 1
+..
+\# Subsection header
+.de Subsection
+.NH 2
+..
+\# Bulleted list item
+.de Bullet
+.IP \[bu]
+..
+\# Set in 12pt font
+.nr PS 12p
+.TL
+CLFormat Documentation
+.AU
+Ben Culkin
+\# No abstract needed
+.AB no
+.AE
+.PP
+CLFormat is an implementation of something that is strongly reminiscent of the
+Common Lisp FORMAT function. I say 'strongly reminiscent', because we don't
+support quite all the directives they, but support several new ones they don't.
+.Section
+Directives
+.PP
+FORMAT strings are made up of free-form text, with all of the functionality
+coming from \fIdirectives\fP. A directive is always started with a tilde, and
+consists of the following parts:
+.IP 1.
+An optional set of \fIprefix parameters\fP
+.IP 2.
+An optional set of \fIdirective modifiers\fP
+.IP 3.
+The name of the directive
+.PP
+To execute a format string, and get it to provide formatting, a set of arguments
+called \fIformat items\fP must be provided. These serve the same purpose as the
+arguments provided to printf and other similar functions after their format
+string.
+.Subsection
+Prefix Parameters
+.RS
+.PP
+Prefix parameters are used to configure the options for a directive. These can
+include things varying from the number of columns to print a field in, to the
+radix that a number should be printed in. They are separated from each by
+commas.
+.PP
+A prefix parameter can be any one of the following:
+.IP "A signed decimal number"
+	The value of this parameter is the provided number.
+.IP "A single character, preceeded by a single-quote"
+	The value of this parameter is the provided character
+.IP "The letter V"
+	The value of this parameter will be read from the format string items.
+.IP "The character #"
+	The value of this parameter will be set to the number of format string
+	parameters remaining
+.IP "The character %"
+	The value of this paramter will be set to the current position in the list
+	of format string items.
+.IP "A double quoted string"
+	The value of this parameter is the represented string.
+.PP
+Prefix parameters are numbered positionally by default, but they can be given a
+name by starting the parameter with a # character, following that with a
+parameter name (which can be any series of printing characters that is not a
+whitespace character, and not one of the following separator characters: ',',
+',', ':' or ';'). It is then followed by a name-separator character (either ':'
+or ';') then its value from the above list.
+.RS
+.SH 3
+Notes
+.PP
+.Bullet
+The difference between ':' and ';' is that if you use ':', that
+parameter can't be addressed positionally, while if you use ';', it still can.
+.Bullet
+If you specify more parameters than a directive is noted to take, the behavior
+is based off of whether you've provided extra named, non-positional parameters or extra
+positional ones. You can specify as many named non-positional parameters as you
+want, and the directive will be fine. However, if you specify more or less
+positional parameters, that is an an error.
+.Bullet
+As a 'useful' feature, when you are naming named parameters, you may abbreviate
+the name to its shortest unambigous value. However, as an exception to the
+normal rule that you can provide unused named parameters, passing an ambiguous
+parameter name will cause an error. For instance, if a directive took the
+parameters 'foo', 'foobar' and 'fizz', these are some of the results:
+.RS
+.IP \f(CRfoo\fP
+	Refers to foo
+.IP foobar
+	Refers to foobar
+.IP foob
+	Refers to foobar
+.IP fizz
+	Refers to fizz
+.IP fi
+	Refers to fizz
+.IP f
+	Error, could refer to foo, foobar or fizz
+.RE
+.RE
+.Subsection
+Directive modifiers
+.RS
+.PP
+Directive modifiers, or \fImodifier sets\fP, are any combination of the
+following characters (with duplicate characters having no effect)
+.Bullet
+.CW "$"
+.Bullet
+.CW ":"
+.Bullet
+.CW "*"
+.Bullet
+.CW "@"
+.RE
+.Subsection
+Directive names
+.RS
+.PP
+A directive name can be either
+.Bullet
+A single, non-whitespace, non-/ character, optionally preceeded by a grave
+.Bullet
+A name bracketed by /
+.PP
+If the directive is a bracketed name, then it is a call to a user-specified
+function. Otherwise, it is an invocation of one of the built-in directives.
+.RE
+.Section
+Directives
+.PP
+The following is a list of all of the directives that are currently implemented,
+as well as a short description of what each directive does.
+.KS
+.TS H
+center allbox ;
+c s s
+c | c | c .
+Directive Overview
+Directive	Name	Brief Description
+_
+.TH
+.T&
+lfCR | l | l .
+A	Aesthetic	General string printer.
+S		Alias for the A directive\[dg]
+C	Character	Print out a single character
+B	Binary	Print out a base-2 integer
+O	Octal	Print out a base-8 integer
+D	Decimal	Print out a base-10 integer
+X	Hexadecimal	Print out a base-16 integer
+R	Radix	Print out an integer in an arbitrary base\[bu]
+&	Fresh Line	Print a newline character, if we didn't just print one
+%	Newline	Print out a literal new line
+|	Formfeed	Print out a 'formfeed' and start a new page
+~	Tilde	Print out a literal tilde
+?	Recursive	Invoke a sub-frmat string
+*	Go-to	Move around in the item list
+^	Escape	Escape from an enclosing directive
+[	Conditional	Select a sub-format string, based on a conditional
+{	Iteration	Repeatedly invoke a sub-format string
+(	Case	Perform case-manipulation on text
+`[	Inflection	Perform inflection (pluralization/singularization) on a sub-format string
+T	Tabulate	Print items in a tabular format
+.TE
+.ce 1
+\fITable 1: Directive Overview\fP
+.KE
+.FS \[dg]
+CommonLisp has S use a slightly different format, but there isn't one that makes
+sense for us to use. In the future, we may either come up with a format, or
+reassign S to do something else entirely
+.FE
+.FS \[bu]
+At some point, it may make sense to remove some of the radix-specific ones, and
+just tell people to use R. However, for now, we're sticking with it.
+.FE
+.PP
+The following are directives that aren't valid for use outside of a specific
+context (usually, they must follow another directive
+.KS
+.TS H
+center allbox ;
+c s s
+c | c | c .
+Context-Sensitive Directives
+Directive	Name	Brief Description
+_
+.TH
+.T&
+lfCR | l | l .
+]	End Conditional	Ends a conditional directive
+;	Clause Separator	Separates two clauses in a block directive
+)	End Case	Ends a case directive
+']	End Inflection	Ends a inflection directive
+<	Inflection Start 	Starts an inflection control
+>	Inflection End	Ends an inflection control
+.TE
+.ce 1
+\fITable 2: Context-Sensitive Directives\fP
+.KE
+.PP
+And the following are directives which have not yet been implemented
+.KS
+.TS H
+center allbox ;
+c s s
+c | c | c .
+Unimplemented Directives
+Directive	Name	Brief Description
+_
+.TH
+.T&
+lfCR | l | l .
+`<	Start Layout	Start a layout-control block
+`>	End Layout	Ends a layout-control block
+F	Fixed-Format Float	Print a floating-point number in a fixed-point format
+E	Exponential Float	Print a engineering-style (1.2e2) floating point number
+G	General Float	Print a general floating point number
+$	Monetary Float	Print a floating point number like currency
+W	String Print	Use the A directive instead
+P	Plural	Use the `[ and `] directives instead
+.TE
+.ce 1
+\fITable 3: Unimplemented Directives\fP
+.KE
+.PP
+The following section contains a detailed reference for the directives mentioned
+above. This details how the directive works, how many parameters it takes, and
+of what sort they should be, and whatever other details are necessary for that
+particular directive.
+.Subsection
+A Directive
+.RS
+.RE
+.PP
+The A directive is the general purpose string formatting directive, serving as
+the equivalent to the S specifier in printf and other similar formats.
+
+It takes either zero, one or four parameters, as well as one format string item.
+.KS
+.TS
+allbox;
+c c
+lfCR l .
+Sample Format String	Description
+~a	Prints out the format string item as a string
+.TE
+.KE