From 0a9fb6d243b891e2b56a5a73eb642e9ec8e81137 Mon Sep 17 00:00:00 2001 From: "Benjamin J. Culkin" Date: Sat, 17 Oct 2020 17:13:15 -0300 Subject: Update documentation --- clformat/docs/clformat.ms | 121 +++++++++++++++++--------------------------- clformat/docs/clformat.tmac | 48 ++++++++++++++++++ 2 files changed, 95 insertions(+), 74 deletions(-) diff --git a/clformat/docs/clformat.ms b/clformat/docs/clformat.ms index 9a36f63..1a2731f 100644 --- a/clformat/docs/clformat.ms +++ b/clformat/docs/clformat.ms @@ -1,19 +1,6 @@ \# 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 +\# Load macros and stuff +.so clformat.tmac .TL CLFormat Documentation .AU @@ -25,47 +12,43 @@ Ben Culkin 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 +.Section "Directive Syntax" 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. +.Numlist +.Numitem +.Italic "An optional set of " "prefix parameters" "." +.Numitem +.Italic "An optional set of " "directive modifiers" "." +.Numitem 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 +.Subsection "Prefix Parameters" 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. +.Defn "A signed decimal number" +The value of this parameter is the provided number. +.Defn "A single character, preceeded by a single-quote" +The value of this parameter is the provided character +.Defn "The letter V" +The value of this parameter will be read from the format string items. +.Defn "The character #" +The value of this parameter will be set to the number of format string +parameters remaining +.Defn "The character %" +The value of this paramter will be set to the current position in the list +of format string items. +.Defn "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 @@ -73,10 +56,7 @@ 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 +.Supersection "Notes" .Bullet The difference between ':' and ';' is that if you use ':', that parameter can't be addressed positionally, while if you use ';', it still can. @@ -93,24 +73,22 @@ 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 +.CWDefn "foo" Refers to foo -.IP foobar +.CWDefn "foobar" Refers to foobar -.IP foob +.CWDefn "foob" Refers to foobar -.IP fizz +.CWDefn "fizz" Refers to fizz -.IP fi +.CWDefn "fi" Refers to fizz -.IP f +.CWDefn "f" Error, could refer to foo, foobar or fizz .RE -.RE -.Subsection -Directive modifiers -.RS -.PP +.Endsupersection +.Endsubsection +.Subsection "Directive modifiers" Directive modifiers, or \fImodifier sets\fP, are any combination of the following characters (with duplicate characters having no effect) .Bullet @@ -121,11 +99,8 @@ following characters (with duplicate characters having no effect) .CW "*" .Bullet .CW "@" -.RE -.Subsection -Directive names -.RS -.PP +.Endsubsection +.Subsection "Directive names" A directive name can be either .Bullet A single, non-whitespace, non-/ character, optionally preceeded by a grave @@ -134,11 +109,10 @@ 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, +.Endsubsection +.Endsection +.Section "Directive List" +The following is a table of all of the directives that are currently implemented, as well as a short description of what each directive does. .KS .TS H @@ -169,7 +143,7 @@ R Radix Print out an integer in an arbitrary base\[bu] [ 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 +\`[ Inflection Perform inflection (pluralization/singularization) on a sub-format string T Tabulate Print items in a tabular format .TE .ce 1 @@ -201,7 +175,7 @@ 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 +\'] End Inflection Ends a inflection directive < Inflection Start Starts an inflection control > Inflection End Ends an inflection control .TE @@ -221,8 +195,8 @@ _ .TH .T& lfCR | l | l . -`< Start Layout Start a layout-control block -`> End Layout Ends a layout-control block +\`< 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 @@ -238,10 +212,7 @@ 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 +.Subsection "A Directive" .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. @@ -256,3 +227,5 @@ Sample Format String Description ~a Prints out the format string item as a string .TE .KE +.Endsubsection +.Endsection diff --git a/clformat/docs/clformat.tmac b/clformat/docs/clformat.tmac index 9cdd0f2..0d7da96 100644 --- a/clformat/docs/clformat.tmac +++ b/clformat/docs/clformat.tmac @@ -2,14 +2,62 @@ \# Section header .de Section .NH 1 +\s+4\\$1\s-4 +\# Place current section title in right corner +.ds RH "\\$1 +.PP +.. +\# Section footer +.de Endsection .. \# Subsection header .de Subsection .NH 2 +\s+2\\$1\s-2 +.RS +.PP +.. +\# Subsection footer +.de Endsubsection +.RE +.. +\# Supersection header +.de Supersection +.NH 3 +\\$1 +.RS +.PP +.. +\# Supersection footer +.de Endsupersection +.RE .. \# Bulleted list item .de Bullet .IP \[bu] .. +\# Simple numbered list +.de Numlist +.nr listitem 0 1 +.. +\# Item in numbered list +.de Numitem +.IP "\\n+[listitem]." +.. +\# Italicize text +.de Italic +.I "\\$2" "\\$3" "\\$1" +.. +\# Definition-list item +.de Defn +.IP "\fB\\$1\fP" +.. +\# Constant-width Definition-list item +.de CWDefn +.IP "\f(CB\\$1\fP" +.. \# Set in 12pt font .nr PS 12p +\# Put manual title in left corner +.ds LH "CLFormat Manual +.DA -- cgit v1.2.3