src/utilities.lisp: Fix docstring formatting.

[sod] / src / sod.1

.\" -*-nroff-*-
.\"
.\" The Sod translator
.\"
.\" (c) 2015 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the Sensible 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 "\-\-backtrace"
Generate a Lisp stack backtrace if an error is encountered.
This is useful when debugging,
if
.B sod
reports unusual errors, or
is complaining unjustifiably about something.
.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 --------------------------------------------------