.\" $Id: explode.man,v 6.10 2012/07/10 17:22:26 ksb Exp $
.\" $Compile: Display%h
.\" $Display: groff -tbl -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): groff -tbl -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/explode.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/explode.1*
.TH EXPLODE 1 LOCAL
.SH NAME
explode - unpack components from aggregated source archives
.SH SYNOPSIS
.ds PN "explode
\fI\*(PN\fP [\fB\-cfinv\fP] [\fB\-d\fP\~\fIdelimiter\fP] [\fB\-e\fP\~\fIextender\fP] [\fB\-I\fP\~\fIdir\fP] [\fB\-o\fP\~\fIprefix\fP] [\fB\-u\fP\~\fIunpack\fP] [\fIfiles\fP]
.br
\fI\*(PN\fP [\fB\-tv\fP] [\fB\-d\fP\~\fIdelimiter\fP] [\fB\-e\fP\~\fIextender\fP] [\fB\-I\fP\~\fIdir\fP] [\fB\-o\fP\~\fIprefix\fP] [\fB\-u\fP\~\fIunpack\fP] [\fIfiles\fP]
.br
\fI\*(PN\fP [\fB\-finv\fP] [\fB\-e\fP\~\fIextender\fP] [\fB\-I\fP\~\fIdir\fP] [\fB\-o\fP\~\fIprefix\fP] [\fIfiles\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-H\fP
.br
\fI\*(PN\fP \fB\-T\fP
.br
\fI\*(PN\fP \fB\-V\fP
.br
\fI\*(PN\fP \fB\-s\fP [\fB\-finSv\fP] [\fB\-e\fP\~\fIextender\fP] [\fB\-I\fP\~\fIdir\fP] [\fB\-o\fP\~\fIprefix\fP] [\fIfiles\fP]

.SH DESCRIPTION
.I Explode
breaks a source file into separate compilation units.
The source text should contain control directives of the form
.br
	\fIdelimiter\fP\fBdirective\fP \fIargument\fP
.br
all of which must begin in column one of a source line.
.PP
A \fBMICE\fP \*(lqlibrary\*(rq or family is the least specific implementaion of
an algorithm.  Unlike a run-time configured routine (like qsort(3))
a MICE family is configured via compile time macros: thus no
efficiency or functionality is lost due to a \*(lqbad fit\*(rq.
.PP
\fBMICE\fP families come packaged in two files: a large source file
and a small header file.
The C source file, for example, may be compiled with
a \-DTEST option to provide a simple test program.  The header file
is intended to provide all the function prototypes needed to use
the family.  Before the library can be configured for a new application
the user should run the C source through \fI\*(PN\fP.
Of course, any additional make(1) descriptions, manual pages, and/or HTML
documents for the library may be kept as well.
.PP
The \fBExplode\fP directive opens a new output stream according to the
following \fIname\fP (eg. \*(lq/*@Explode \fIname\fP@*/\*(rq for C text).
The name is assumed to end at either the first white-space character or
the first occurrence of the last character in \fIdelimiter\fP.
The \fIname\fP is prefixed by \fIprefix\fP and extended by \fIextender\fP;
the resulting string is passed to fopen(3) as a file name.
.PP
The \fBAppend\fP directive opens a new output stream according to the
following \fIname\fP.  The \fIname\fP is treated as if it were for
an \fBExplode\fP directive, but the file is opened for append and
no header is prefixed to it.
.PP
The \fBHeader\fP directive instructs \fI\*(PN\fP to begin saving a
header that should be copied to the beginning of all the output files.
This directive has no argument (yet).  To remove this from the
output see \fB\-c\fP below.
.PP
The \fBRemove\fP directive diverts text to the null device until another
directive opens a new destination.
.PP
The \fBMessage\fP directive diverts text to the invokers tty until
another directive opens a new destination.
.PP
The \fBInsert\fP directive copies its argument to the current output
stream.  The first non-white character of the argument is taken to be a
delimiter that marks the end of the string.
.PP
The \fBShell\fP directive copies the output of the given \fBsh\fP(1)
command to the current output stream.
The shell command is enclosed in quotes (any non-white character).
.SH OPTIONS
.TP
\fB\-H\fP
Give a short file format reminder.
.TP
\fB\-c\fP
Under this flag none of the exploded modules will have the Header
section included.  This is useful when they are to be subsequently
textually included in another file (via \fIcpp\fP or the like).
.TP
\fB\-d\fP \fIdelimiter\fP
Use the given \fIdelimiter\fP rather than the default for the current
extender. Delimiters should
be short strings. The table below gives some of the default delimiters:
.br
.RS +6
.TS
c c c.
extension	language	default delimiter
c or h	C	/*@
k	K	/*@
f	FORTRAN	c@
p	Pascal	(*@
sh	sh	#@
csh	csh	#@
.TE
.RE
.TP
\fB\-e\fP \fIextender\fP
In an \fBExplode\fP directive, the \fIextender\fP will be
added to the \fIbasename\fP.  By default it is the extender
of the source file, or \*(lq.c\*(rq if no extender can be found.
.TP
\fB\-f\fP
Normally \fI\*(PN\fP will not overwrite existing files: if this option
is given it will.
.TP
\fB\-h\fP
Output a usage line (only).
.TP
\fP\-n\fP
Print what would be done but don't build files.
This option implies the \fB\-v\fP option.
.TP
\fB\-o\fP \fIprefix\fP
In an \fBExplode\fP directive the \fIprefix\fP will be
placed before the \fIbasename\fP.  By default it is the basename of
the file being read.  a \fIprefix\fP of dash (\*(lq-\*(rq) directs
the output to \fIstdout\fP.
.TP
\fB\-s\fP
Output only the source module located (do not explode it into the
parts).
This option is often used to copy source modules to a temporary directory.
.TP
\fB\-S\fP
Just display the path to the source file we located.
.TP
\fB\-u\fP \fIunpack\fP
Cause \fI\*(PN\fP to unpack only the listed files. \fIUnpack\fP may
be a list of names separated by commas.  This option my be repeated
to concatenate the lists.
.TP
\fB\-v\fP
Output a running synopsis of \fI\*(PN\fP's actions.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-o /tmp/foo \-e .c kevin
.fi
To unpack the file \*(lqkevin\*(rq to /tmp/foo\fIbasename\fP.c
which should create /tmp/fooone.c and /tmp/footwo.c.
.TP
.nf
\fI\*(PN\fP \-o /tmp/avl \-u ins \-u del \-u init avl.c
.fi
Only unpack the insert, delete and init routines from the AVL source
file.
.TP
.nf
\fI\*(PN\fP \-t mk.c
.fi
Extract the catalog of available components from the mk.c module.
.TP
.nf
\fI\*(PN\fP \-o \- \-u utemps mk.c |${PAGER:\-more}
.fi
Output the unix domain socket code from the mktemp emulation library
to \fIstdout\fP, send that output to a pager.
.TP
.nf
\fI\*(PN\fP \-T |${PAGER:\-more}
.fi
Output the list of all the default markup expected for each extender.


.SH BUGS
There is no inverse of the \-c option: that is there is no (good) way
to just get the Header section of the archive.  Using \fBdiff\fP(1) to
get it is an unnecessary hack: you almost never need the header without
at least one function.

.SH AUTHOR
KS Braunsdorf, NonPlayer Character Guild
.br
mkcmd and no-spam on ksb.npcguild.org
.PP
This is a modification of the original Purdue code, by the original author.
Since Purdue doesn't distribute explode anymore -- you might have to live
with this version.

.SH "SEE ALSO"
.hlm 0
explode(5l), make(1), cc(1), sh(1), mkcmd(1l)