From 9ed8eb2a733b394af7e956708f2d6aa6a85e526a Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Thu, 22 Oct 2015 00:46:28 +0100
Subject: [PATCH] lib/, src/: Add man pages for the translator.

Rather sketchy for now.  This will improve later, no doubt.
---
 lib/sod-structs.3 |   2 +
 lib/sod.3         |   3 +
 src/Makefile.am   |   6 +
 src/sod-module.5  | 836 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/sod.1         | 188 ++++++++++++
 5 files changed, 1035 insertions(+)
 create mode 100644 src/sod-module.5
 create mode 100644 src/sod.1

diff --git a/lib/sod-structs.3 b/lib/sod-structs.3
index bc181ee..5846079 100644
--- a/lib/sod-structs.3
+++ b/lib/sod-structs.3
@@ -23,7 +23,9 @@
 .\" along with SOD; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 .
+.\" Highlight using terminal escapes, rather than overstriking.
 .\"\X'tty: sgr 1'
+.
 .\" String definitions and font selection.
 .ie t \{\
 .  ds o \(bu
diff --git a/lib/sod.3 b/lib/sod.3
index 83d004b..bfdc1e5 100644
--- a/lib/sod.3
+++ b/lib/sod.3
@@ -23,7 +23,9 @@
 .\" along with SOD; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 .
+.\" Highlight using terminal escapes, rather than overstriking.
 .\"\X'tty: sgr 1'
+.
 .\" String definitions and font selection.
 .ie t \{\
 .  ds o \(bu
@@ -364,6 +366,7 @@ macro instead.
 .
 .\"--------------------------------------------------------------------------
 .SH SEE ALSO
+.BR sod (1),
 .BR sod-structs (3).
 .
 .\"--------------------------------------------------------------------------
diff --git a/src/Makefile.am b/src/Makefile.am
index 28804c6..bd068d1 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -160,6 +160,12 @@ check-local: sod sod-test.asd
 			(cl-launch:quit 1)))'
 
 ###--------------------------------------------------------------------------
+### Manual pages.
+
+dist_man_MANS		+= sod.1
+dist_man_MANS		+= sod-module.5
+
+###--------------------------------------------------------------------------
 ### Installation.
 
 ## We want a symlink $(lispsysdir)/sod.asd -> $(lispsrcdir)/sod/sod.asd.  It
diff --git a/src/sod-module.5 b/src/sod-module.5
new file mode 100644
index 0000000..44f7f8a
--- /dev/null
+++ b/src/sod-module.5
@@ -0,0 +1,836 @@
+.\" -*-nroff-*-
+.\"
+.\" The Sod module syntax
+.\"
+.\" (c) 2015 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the Sensble Object Design, an object system for C.
+.\"
+.\" SOD is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" SOD is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with SOD; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\" Highlight using terminal escapes, rather than overstriking.
+.\"\X'tty: sgr 1'
+.
+.\" String definitions and font selection.
+.ie t \{\
+.  ds o \(bu
+.  if \n(.g .fam P
+.\}
+.el \{\
+.  ds o o
+.\}
+.
+.\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.
+.\" An epsilon, or e.
+.ie t \{\
+.  ds e \(*e
+.  ds ^ \v'-.3m'\s'\\n(.s*7/10'
+.  ds ^e \s0\v'.3m'
+.  ds _ \v'.3m'\s'\\n(.s*7/10'
+.  ds _e \s0\v'-.3m'
+.\}
+.el \{
+.  ds e \fIe\fR
+.  ds ^ ^
+.  ds ^e
+.  ds _ _
+.  ds _e
+.\}
+.ds * \*^\(**\*(^e
+.ds + \*^+\*(^e
+.
+.de |
+.br
+\h'4n'|
+..
+.ie t \{\
+.  de <
+..
+.\}
+.el
+.  de <
+.    br
+\h'4n'
+..
+.\}
+.
+.\"--------------------------------------------------------------------------
+.TH sod 5 "11 October 2015" "Straylight/Edgeware" "Sensible Object Design"
+.
+.SH NAME
+sod-module \- Sensible Object Design module syntax
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+This manual page provides a highly compressed description of the
+Sod module syntax.
+For full details, consult the main manual.
+.PP
+.SS Notation
+Anywhere a simple nonterminal name
+.I x
+may appear in the grammar,
+an
+.I indexed
+nonterminal
+.IR x [ a \*_1\*(_e,
+\&...,
+.IR a \*_ n \*(_e]
+may also appear.
+On the left-hand side of a production rule,
+the indices
+.IR a \*_1\*(_e,
+\&...,
+.IR a \*_ n \*(_e
+are variables which vary over all nonterminal and terminal symbols,
+and the variables may also appear on the right-hand side
+in place of a nonterminal.
+Such a rule stands for a family of rules,
+in each variable is replaced by
+each possible simple nonterminal or terminal symbol.
+.PP
+The letter \*e denotes the empty nonterminal
+.IP
+.I \*e
+::=
+.PP
+The following indexed productions are used throughout the grammar, some often
+enough that they deserve special notation.
+.hP \*o
+.RI [ x ]
+abbreviates
+.IR optional [ x ],
+denoting an optional occurrence of
+.IR x :
+.RS
+.IP
+.RI [ x ]
+::=
+.IR optional [ x ]
+::=
+\*e
+|
+.I x
+.RE
+.hP \*o
+.IR x \**
+abbreviates
+.IR zero-or-more [ x ],
+denoting a sequence of zero or more occurrences of
+.IR x :
+.RS
+.IP
+.IR x \**
+::=
+.IR zero-or-more [ x ]
+::=
+\*e
+|
+.I x
+.IR x \**
+.RE
+.hP \*o
+.IR x \*+
+abbreviates
+.IR one-or-more [ x ]
+denoting a sequence of one or more occurrences of
+.IR x :
+.RS
+.IP
+.IR x \*+
+::=
+.IR one-or-more [ x ]
+::=
+.I x
+.IR x \**
+.RE
+.hP \*o
+.IR list [ x ]
+denotes a sequence of one or more occurrences of
+.I x
+separated by commas:
+.RS
+.IP
+.IR list [ x ]
+::=
+.I x
+|
+.IR list [ x ]
+.B ,
+.I x
+.RE
+.
+.SS Special nonterminals
+.I s-expression
+::=
+an S-expression, as parsed by the Lisp reader
+.br
+.I c-fragment
+::=
+a sequence of C tokens, with matching brackets
+.
+.\"--------------------------------------------------------------------------
+.SH LEXICAL SYNTAX
+.
+.SS Tokens
+.I token
+::=
+.I identifier
+.|
+.I string-literal
+.|
+.I char-literal
+.|
+.I integer-literal
+.|
+.I punctuation
+.
+.SS Identifiers
+.I identifier
+::=
+.I id-start-char
+.IR id-body-char \**
+.br
+.I id-start-char
+::=
+.I alpha-char
+|
+.B _
+.br
+.I id-body-char
+::=
+.I id-start-char
+|
+.I digit-char
+.br
+.I alpha-char
+::=
+.B A
+|
+.B B
+| ... |
+.B Z
+.|
+.B a
+|
+.B b
+| ... |
+.B z
+.|
+.I extended-alpha-char
+.br
+.I digit-char
+::=
+.B 0
+|
+.I nonzero-digit-char
+.br
+.I nonzero-digit-char
+::=
+.B 1
+|
+.B 2
+| ... |
+.B 9
+.PP
+The characters matched by
+.I extended-alpha-char
+depend on the locale and the host Lisp system.
+.
+.SS String and character literals
+.I string-literal
+::=
+.B """"
+.IR string-literal-char \**
+.B """"
+.br
+.I char-literal
+::=
+.B '
+.IR char-literal-char \**
+.B '
+.br
+.I string-literal-char
+::=
+any character other than
+.B \e
+or
+.B """"
+.|
+.B \e
+.I char
+.br
+.I char-literal-char
+::=
+any character other than
+.B \e
+or
+.B '
+.|
+.B \e
+.I char
+.
+.SS Integer literals
+.I integer-literal
+::=
+.I decimal-integer
+.|
+.I binary-integer
+.|
+.I octal-integer
+.|
+.I hex-integer
+.br
+.I decimal-integer
+::=
+.B 0
+|
+.I nonzero-digit-char
+.IR digit-char \**
+.br
+.I binary-integer
+::=
+.B 0
+.RB ( b | B )
+.IR binary-digit-char \*+
+.br
+.I binary-digit-char
+::=
+.B 0
+|
+.B 1
+.br
+.I octal-integer
+::=
+.B 0
+.RB [ o | O ]
+.IR octal-digit-char \*+
+.br
+.I octal-digit-char
+::=
+.B 0
+|
+.B 1
+| ... |
+.B 7
+.br
+.I hex-integer
+::=
+.B 0
+.RB ( x | X )
+.IR hex-digit-char \*+
+.br
+.I hex-digit-char
+::=
+.I digit-char
+.|
+.B A
+|
+.B B
+|
+.B C
+|
+.B D
+|
+.B E
+|
+.B F
+.|
+.B a
+|
+.B b
+|
+.B c
+|
+.B d
+|
+.B e
+|
+.B f
+.
+.SS Punctuation
+.I punctuation
+::=
+any non-alphanumeric character
+other than
+.BR _ ,
+.BR """" ,
+or
+.B '
+.
+.SS Comments
+.I comment
+::=
+.I block-comment
+.|
+.I line-comment
+.br
+.I block-comment
+::=
+.<
+.B /*
+.IR not-star \**
+.RI ( star \*+
+.I not-star-or-slash
+.IR not-star \**)\**
+.IR star \**
+.B */
+.br
+.I star
+::=
+.B *
+.br
+.I not-star
+::=
+any character other than
+.B *
+.br
+.I not-star-or-slash
+::=
+any character other than
+.B *
+or
+.B /
+.br
+.I line-comment
+::=
+.B //
+.IR not-newline \**
+.I newline
+.br
+.I newline
+::=
+a newline character
+.br
+.I not-newline
+::=
+any character other than newline
+.
+.\"--------------------------------------------------------------------------
+.SH MODULE SYNTAX
+.
+.I module
+::=
+.IR definition \**
+.br
+.I definition
+::=
+.I import-definition
+.|
+.I load-definition
+.|
+.I lisp-definition
+.|
+.I typename-definition
+.|
+.I code-definition
+.|
+.I class-definition
+.
+.SS Simple definitions
+.I import-definition
+::=
+.B import
+.I string-literal
+.B ;
+.br
+.I load-definition
+::=
+.B load
+.I string-literal
+.B ;
+.br
+.I lisp-definition
+::=
+.B lisp
+.I s-expression
+.B ;
+.br
+.I typename-definition
+::=
+.B typename
+.IR list [ identifier ]
+.B ;
+.
+.SS Literal code fragments
+.br
+.I code-definition
+::=
+.<
+.B code
+.I identifier
+.B
+.I identifier
+.RI [ constraints ]
+.B {
+.I c-fragment
+.B }
+.br
+.I constraints
+::=
+.B [
+.IR list [ constraint ]
+.B ]
+.br
+.I constraint
+::=
+.IR identifier \*+
+.
+.SS Class definitions
+.I
+class-definition
+::=
+.I class-forward-declaration
+.|
+.I full-class-definition
+.br
+.I class-forward-declaration
+::=
+.B class
+.I identifier
+.B ;
+.br
+.I full-class-definition
+::=
+.RI [ properties ]
+.<
+.B class
+.I identifier
+.B :
+.IR list [ identifier ]
+.<
+.B {
+.IR class-item \**
+.B }
+.br
+.I class-item
+::=
+.I slot-item
+.|
+.I initializer-item
+.|
+.I message-item
+.|
+.I method-item
+.br
+.I slot-item
+::=
+.<
+.RI [ properties ]
+.IR declaration-specifier \*+
+.IR list [ init-declarator ]
+.B ;
+.br
+.I init-declarator
+::=
+.I simple-declarator
+.RB [ =
+.IR initializer ]
+.br
+.I initializer-item
+::=
+.RI [ properties ]
+.RB [ class ]
+.IR list [ slot-initializer ]
+.B ;
+.br
+.I slot-initializer
+::=
+.I dotted-name
+.B =
+.I initializer
+.br
+.I initializer
+::=
+.B {
+.I c-fragment
+.B }
+|
+.I c-fragment
+.br
+.I message-item
+::=
+.RI [ properties ]
+.<
+.IR declaration-specifier \*+
+.I simple-declarator
+.<
+.RI [ method-body ]
+.br
+.I method-item
+.RI [ properties ]
+.<
+.IR declaration-specifier \*+
+.I dotted-declarator
+.<
+.I method-body
+.br
+.I method-body
+::=
+.B {
+.I c-fragment
+.B }
+|
+.B extern
+.B ;
+.
+.SS Property sets
+.I properties
+::=
+.B [
+.IR list [ property ]
+.B ]
+.br
+.I property
+::=
+.I identifier
+.B =
+.I expression
+.br
+.I expression
+::=
+.I term
+|
+.I expression
+.B +
+.I term
+|
+.I expression
+.B \-
+.I term
+.br
+.I term
+::=
+.I factor
+|
+.I term
+.B *
+.I factor
+|
+.I term
+.B /
+.I factor
+.br
+.I factor
+::=
+.I primary
+|
+.B +
+.I factor
+|
+.B \-
+.B factor
+.br
+.I primary
+::=
+.I integer-literal
+|
+.I string-literal
+.ie t |
+.el .|
+.I char-literal
+|
+.I identifier
+.|
+.B ?
+.I s-expression
+.|
+.B (
+.I expression
+.B )
+.
+.SS C types
+.I declaration-specifier
+::=
+.I type-name
+.|
+.B struct
+.I identifier
+|
+.B union
+.I identifier
+|
+.B enum
+.I identifier
+.|
+.B void
+|
+.B char
+|
+.B int
+|
+.B float
+|
+.B double
+.|
+.B short
+|
+.B long
+.|
+.B signed
+|
+.B unsigned
+.|
+.I qualifier
+.br
+.I qualifier
+::=
+.B const
+|
+.B volatile
+|
+.B restrict
+.br
+.I type-name
+::=
+.I identifier
+.PP
+Declaration specifiers may appear in any order.
+However, not all combinations are permitted.
+A declaration specifier must consist of 
+zero or more qualifiers,
+and one of the following, up to reordering.
+.hP \*o
+.I type-name
+.hP \*o
+.B struct
+.IR identifier ,
+.B union
+.IR identifier ,
+.B enum
+.I identifier
+.hP \*o
+.B void
+.hP \*o
+.BR char ,
+.BR "unsigned char" ,
+.B "signed char"
+.hP \*o
+.BR short ,
+.BR "unsigned short" ,
+.B "signed short"
+.hP \*o
+.BR "short int" ,
+.BR "unsigned short int" ,
+.B "signed short int"
+.hP \*o
+.BR int ,
+.BR "unsigned int" ,
+.BR "signed int" ,
+.BR unsigned ,
+.B signed
+.hP \*o
+.BR long ,
+.BR "unsigned long" ,
+.B "signed long"
+.hP \*o
+.BR "long int" ,
+.BR "unsigned long int" ,
+.B "signed long int"
+.hP \*o
+.BR "long long" ,
+.BR "unsigned long long" ,
+.B "signed long long"
+.hP \*o
+.BR "long long int" ,
+.BR "unsigned long long int" ,
+.B "signed long long int"
+.hP \*o
+.BR float ,
+.BR double ,
+.B long double
+.PP
+.IR declarator [ k ]
+::=
+.IR pointer \**
+.IR primary-declarator [ k ]
+.br
+.IR primary-declarator [ k ]
+::=
+.I k
+.|
+.B (
+.IR primary-declarator [ k ]
+.B )
+.|
+.IR primary-declarator [ k ]
+.IR declarator-suffix
+.br
+.I pointer
+::=
+.B *
+.IR qualifier \**
+.br
+.I declarator-suffix
+::=
+.B [
+.I c-fragment
+.B ]
+.|
+.B (
+.I arguments
+.B )
+.br
+.I arguments
+::=
+\*e |
+.B ...
+.|
+.IR list [ argument ]
+.RB [ ,
+.BR ... ]
+.br
+.I argument
+::=
+.IR declaration-specifier \*+
+.I argument-declarator
+.br
+.I argument-declarator
+::=
+.IR declarator [ identifier " | \*e]"
+.br
+.I simple-declarator
+::=
+.IR declarator [ identifier ]
+.br
+.I dotted-name
+::=
+.I identifier
+.B .\&
+.I identifier
+.br
+.I dotted-declarator
+::=
+.IR declarator [ dotted-name ]
+
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.BR sod (1),
+.BR sod (3),
+.BR sod-structs (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
diff --git a/src/sod.1 b/src/sod.1
new file mode 100644
index 0000000..3c9ef64
--- /dev/null
+++ b/src/sod.1
@@ -0,0 +1,188 @@
+.\" -*-nroff-*-
+.\"
+.\" The Sod translator
+.\"
+.\" (c) 2015 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the Sensble Object Design, an object system for C.
+.\"
+.\" SOD is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" SOD is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with SOD; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\" Highlight using terminal escapes, rather than overstriking.
+.\"\X'tty: sgr 1'
+.
+.\" String definitions and font selection.
+.ie t \{\
+.  ds o \(bu
+.  if \n(.g .fam P
+.\}
+.el \{\
+.  ds o o
+.\}
+.
+.\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.
+.\"--------------------------------------------------------------------------
+.TH sod 1 "11 October 2015" "Straylight/Edgeware" "Sensible Object Design"
+.
+.SH NAME
+sod \- Sensible Object Design translator
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.B sod
+.RB [ \-p ]
+.RB [ \-\-builtins ]
+.RB [ \-d
+.IR dir ]
+.RB [ \-I
+.IR dir ]
+.RB [ \-t
+.IR out-type ]
+.IR sources ...
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B sod
+program reads input files describing Sod modules,
+containing class definitions and other items,
+and generates output files,
+such as C source and header files.
+.
+.SS Command line
+The following command-line options are recognized.
+.TP
+.B "\-h, \-\-help"
+Write command-line help text to standard output,
+and exit successfully.
+.TP
+.B "\-V, \-\-version"
+Write Sod's version number to standard output,
+and exit successfully.
+.TP
+.B "\-u, \-\-usage"
+Write a brief usage message to standard output,
+and exit successfully.
+.TP
+.B "\-\-builtins"
+Generate output for to the built-in module,
+which defines the root classes
+.B SodObject
+and
+.BR SodClass .
+For the purpose of naming output files,
+the built-in module is named
+.BR sod-base .
+.TP
+.BI "\-I, \-\-include=" dir
+Look for imported modules and extension files in directory
+.IR dir .
+This option may be repeated:
+directories are searched in the order they were named.
+.TP
+.BI "\-d, \-\-directory=" dir
+Write output files to directory
+.IR dir ,
+instead of the current directory.
+.TP
+.B "\-p, \-\-stdout"
+Write output to standard output,
+instead of to files.
+.TP
+.BI "\-t, \-\-type=" out-type
+Produce output of type
+.IR out-type .
+Output types can be defined by extensions.
+The built-in output types are described below.
+.PP
+Each
+.I source
+file named on the command-line
+is read and parsed as a Sod module:
+see
+.BR sod-module (5)
+for the built-in syntax.
+An output file is written for each module read,
+and the built-in module if the
+.B \-\-builtins
+option was given,
+and for each output type requested using the
+.B \-t
+option.
+At least one output type must be provided.
+.
+.SS Output types
+If a module is read from a file named
+.IB name . ext
+where
+.I ext
+doesn't contain a dot
+.RB (` . '),
+or if the file has a simple
+.I name
+which doesn't contain a dot
+(except possibly an initial one),
+then the module's name is
+.IR name .
+It is conventional for module files to be named
+.IB name .sod \fR.
+Output file names are determined by the module name,
+the output type,
+and the output directory
+.I dir
+specified by the
+.B \-d
+option.
+.PP
+The following output types are defined.
+.TP
+.B c
+Write C source,
+suitable for standalone compilation,
+defining the necessary direct and effective method functions
+and static tables
+for the classes defined in the module.
+The output file is named
+.IB dir / name .c \fR.
+.TP
+.B h
+Write a C header file,
+suitable for inclusion using
+.BR #include ,
+declaring the necessary data structures and functions
+for the classes defined in the module.
+The output file is named
+.IB dir / name .h \fR.
+.
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.BR sod (3),
+.BR sod-structs (3),
+.BR sod-module (5).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
-- 
2.11.0