.\" $Id: efmd.man,v 1.28 2012/10/31 20:23:49 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -tbl -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff-groff} -tbl -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/efmd.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt][18]/efmd.8*
.TH EFMD 8 LOCAL
.SH NAME
efmd - extraction filter for meta data files
.SH SYNOPSIS
.ds PN "efmd
.\" extract, examine, expand, explain, extol
.\" from, filter, for, functions-from, fabricated, fold
.\" meta, msrc, master, many, m4, macro, making
.\" data, deltas, destination, descriptions, differences, deletions
\fI\*(PN\fP [\fB\-n\fP] [\fB\-B\fP\~\fImacros\fP] [\fB\-C\fP\~\fIconfigs\fP] [\fB\-d\fP\~\fIflags\fP] [\fB\-D\fP|\fBI\fP|\fBU\fP\~\fIm4-opts\fP] [\fB\-E\fP\~\fIcompares\fP] [\fB\-F\fP\~\fIliteral\fP] [\fB\-G\fP\~\fIguard\fP] [\fB\-j\fP\~\fIm4prep\fP] [\fB\-k\fP\~\fIkey\fP] [\fB\-M\fP\~\fIprefix\fP] [\fB\-o\fP\~\fIattributes\fP] [\fB\-T\fP\~\fIheader\fP] [\fB\-X\fP\~\fIex-configs\fP] [\fB\-Y\fP\~\fItop\fP] [\fB\-Z\fP\~\fIzero-config\fP] [\fIarguments\fP]
.br
\fI\*(PN\fP \fB\-L\fP [\fB\-B\fP\~\fImacros\fP] [\fB\-C\fP\~\fIconfigs\fP] [\fB\-d\fP\~\fIflags\fP] [\fB\-D\fP|\fBI\fP|\fBU\fP\~\fIm4-opts\fP] [\fB\-E\fP\~\fIcompares\fP] [\fB\-G\fP\~\fIguard\fP] [\fB\-j\fP\~\fIm4prep\fP] [\fB\-k\fP\~\fIkey\fP] [\fB\-M\fP\~\fIprefix\fP] [\fB\-o\fP\~\fIattributes\fP] [\fB\-X\fP\~\fIex-configs\fP] [\fB\-Y\fP\~\fItop\fP] [\fB\-Z\fP\~\fIzero-config\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
\fBEfmd\fP extracts attributes from \fBhxmd\fP meta data files into
a stream on \fIstdout\fP.  This replaces the \fB\-E\fP option to
the old \fBdistrib\fP application.  If you find yourself running
the \fBecho\fP command as the only shell command in an \fBhxmd\fP
\fIcontrol\fP string, then you really wanted this program.

.P
Sometimes you just want a text report from the \fBhxmd\fP configuration
data, not to fork hundreds of parallel processes.  In that case you
want \fI\*(PN\fP, which only forks 2 \fBm4\fP processes to generate
even the longest report.  (One to select the hosts, one to output
the report.)
.P
The main advantage of \fI\*(PN\fP over \fBhxmd\fP is in a pipeline:
\fI\*(PN\fP can read \fIstdin\fP and write to \fIstdout\fP, where
\fBhxmd\fP may output results in a permuted order (due to
the parallel process model it uses).
.P
Using \fBhxmd\fP to produce simple reports is also very costly.
Common results are 8x to 50x faster when \fI\*(PN\fP replaces
\fBhxmd\fP for same text report generation.  For longer reports
the factor gets substantially larger, as many more process \fBfork\fPs
are avoided.
.P
The \fIarguments\fP consist of regular files, FIFOs, literal strings,
and/or cache directories (which must contain a "Cache.m4" recipe file
marked-up in \fBm4\fP).
.P
The \fBm4\fP environment is almost identical to \fBhxmd\fP's, except
the \fBHXMD_PHASE\fP lever only has two values: "selection" and "output".
The processing of each \fIarguments\fP is undifferentiated by
counting numbers, since the same \fBm4\fP process filters them all.
This does allow an included macro file to tell which program summoned
it for inclusion, don't depend on that Easter Egg.

.SH OPTIONS
If the program is called as \fI\*(PN\fP then no options are forced.
When the program is called with a name other than the usual that
name is treated as the basename of a default configuration file.
Almost all of these options are taken from \fBhxmd\fP, so you should
read about them there.  I'm not going to repeat all the selection
logic here.
.TP
\fB\-B\fP \fImacros\fP
Boolean check, macros must be defined to select host, as in \fBhxmd\fP.
.TP
\fB\-C\fP \fIconfigs\fP
Files of hosts and attribute macros, colon separated.
This option accumulates words separated by ``:''.
.TP
\fB\-d\fP \fIflags\fP
Debug flags we pass on to m4 ('?' for help).
.TP
\fB\-D\fP \fImacro\fP[=\fIvalue\fP] | \fB\-I\fP \fIfile\fP | \fB\-U\fP \fImacro\fP
Pass an option down to \fBm4\fP(1).
.TP
\fB\-E\fP \fIcompares\fP
Macro value must satisfy given relation to select hosts.
.TP
\fB\-F\fP \fIliteral\fP
The number of parameters which are literal text (default 1).  Processed
as \fBhxmd\fP does: negative values counted from the right, positive from
the left.  Remaining \fIarguments\fP are taken as files or cache directories.
.TP
\fB\-G\fP \fIguard\fP
Expressions to select hosts by name.  See \fBhxmd\fP(8).
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-j\fP \fIm4prep\fP
Each \fIm4prep\fP file contains macro definitions for \fBm4\fP that
may be consulted in any subsequent expansion.  It is not a good idea
to include any directive that has output, as in \fBhxmd\fP.
.TP
\fB\-k\fP \fIkey\fP
Change the merge macro name from HOST to \fIkey\fP.
.TP
\fB\-L\fP
List the keys selected, but to not process any positional parameters.
This is the cheap way to convert a configuration file into just a list of
hosts (for \fBxapply\fP or other similar filters).
.TP
\fB\-M\fP \fIprefix\fP
Replace the \fBHXMD_\fP macro prefix with \fIprefix\fP.  This option
is not included in the on-line help message, as most of the time it
would be a bad idea to change it.
.TP
\fB\-n\fP
Do not execute commands, trace only.  The output is a long
\fBm4\fP markup script.  This helps explain how things work, and
might help you debug broken markup.
.TP
\fB\-o\fP \fIattributes\fP
Output format of the merged configuration file.
This option accumulates words separated by tab (``\et'').
The name of the merged configuration file is always defined on
the command-line passed to \fBm4\fP as the first \fB\-D\fP option.
That makes \fI$1\fP "\-D" and \fI$2\fP "HXMD_U_MERGED=\fIpath\fP".
.\" see the regression test ereg.ksh in the source directory.
.TP
\fB\-T\fP \fIheader\fP
Output each of these at the top of the \fIm4\fP markup.
This is used for headers, to setup diversions, or to install wrap logic.
There is no "footer" hook since \fIm4wrap\fP works just fine.
.TP
\fB\-V\fP
Show only version information.
.TP
\fB\-X\fP \fIex-configs\fP
Add attribute macro data to defined hosts, colon separated.
.TP
\fB\-Y\fP \fItop\fP
M4 commands included at the top of the guard processing.
.TP
\fB\-Z\fP \fIzero-config\fP
Configuration files to set default macro values.
This option accumulates words separated by ``:''.

.SH ENVIRONMENT
.TP
\fBHXMD_LIB\fP
As in \fBhxmd\fP, read configuration files from this path.
Also treat the first absolute path as the double-dash directory.
.TP
\fBM4_PATH\fP
If set we prefer this program as the path to \fBm4\fP.  This does
allow some clever hooks \*(Tm.  Building a script that additionally
processes the input markup from \fIstdin\fP before passing it to
\fBm4\fP, or passes it to \fBm4\fP then takes some other action
on the output before exiting might be clever.
For example, this is the best way to use \fIHXMD_U_MERGED\fP in
a recursive call.
.TP
\fBTMPDIR\fP
As always, the path to the preferred temporary file space (default
\fB/tmp\fP).

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-C example.cf \-\- "HOST ADMIN"
.fi
Report the hostname and administrator for each host in \fBexample.cf\fP.
.TP
.nf
\fI\*(PN\fP \-C example.cf \-F1 HOST stock.m4
.fi
Report the name of the host and all the data requested by \fBstock.m4\fP
for each host from the first example.  Note that "\-F1" is the default.
.TP
.nf
\fI\*(PN\fP \-I \-\- \-j class.m4 \-C some.cf "HOST CLASSOF(HOST)"
.fi
Use a local macro from "class.m4" to map each host to it's class.
This assumes that the file "class.m4" contains a definition
of the "CLASSOF" function, and no extra text (which would be noise
in the output stream).  The \fB\-I\fP specification helps locate
the header file, if it is in the default search directory.
.TP
.nf
\fI\*(PN\fP \-V
.fi
Shows the version of \fI\*(PN\fP, also the version of the common
modules taken from \fBhxmd\fP.
.TP
.nf
\fI\*(PN\fP \-C any.cf \-D M \-F0
.fi
Just check the file \fBany.cf\fP for structure.  No host are selected
and no output should be generated.  Any output from the
configuration file reader or from \fBm4\fP represent errors in the
the syntax of the file, or the markup in the attributes.
.TP
.nf
\fI\*(PN\fP \-C all.cf \-E SHORTHOST=sulaco \-j common.m4 \-F0 header.m4 body.m4 next.m4
.fi
Build a report for the host \fBsulaco\fP from the markup in
the three listed files, and the functions in the common file.
.TP
.nf
M4_PATH=`which less` \fI\*(PN\fP \-C any.cf \-F0
.fi
Page the base markup to debug error reports from \fBm4\fP.
.TP
.nf
\fI\*(PN\fP \-L \-C cvt.cf \-E HOSTTYPE!unknown >host.cl
.fi
Convert the configuration in "cvt.cf" to a list of hosts, but skip
the ones with \fIHOSTTYPE\fP set to "unknown".
.TP
.nf
\fI\*(PN\fP \-L \-k SHORTHOST \-C cvt.cf \-E HOSTTYPE!unknown >host.cl
.fi
This shows where \fB\-L\fP differs from just putting \fBHOST\fP on
the end of the command: since the key macro is \fBSHORTHOST\fP that is the
column selected, and it only \fBfork\fP(2)'s a single \fBm4\fP process.
.TP
.nf
\fI\*(PN\fP -G"ifelse(yes,SERVICES(dns),HOST,yes,SERVICES(nis),HOST,yes,SERVICES(mux),HOST)" -Csite.cf -L
.fi
List any host that provides at least 1 of these three services:
\fBdns\fP, \fBnis\fP, or \fBmux\fP.  This is an \*(lqor\*(rq operation.
.TP
.nf
\fIcmd\fP |\fI\*(PN\fP \-C \- ... \-o ... \-T "paste(HXMD_U_MERGED)dnl" dnl
.fi
Use \fI\*(PN\fP as a configuration file filter: specify the selection
criteria and the desired output format to complete the form.  By using
the markup "dnl" for each host we emit no text for the hosts, while the
top markup includes the text of the merged configuration file literally.
.TP
.nf
\fI\*(PN\fP \-C $FILE \-T HXMD_OPT_C dnl
.fi
Convert the configuration filename given in "$FILE" into
a full path to the file.
If the result contains a colon it may be more than 1 file, or a filename
with an embedded colon.
.P
An example shim for \fBM4_PATH\fP that mocks \fB\-n\fP:
.RS
.nf
#!/bin/sh
# Show exactly what efmd would process
(
echo $(which m4) $* '<<\e!'
cat \-
echo '\e!'
) | ${PAGER:\-more}
exit 0
.fi
.RE

.SH BUGS
\fIEfmd\fP masquerades as \fBhxmd\fP in terms of macro defines:
it would be much harder to test markup for the two programs when they
used different macro names.
The hidden option \fB\-M\fP replaces the default macro prefix \fBHXMD_\fP
with one of your choosing, should you need that.
.P
Access to cache directories by \fI\*(PN\fP is very expensive: almost as
costly as running \fBhxmd\fP.  It is also likely that, for want of
\fB\-K\fP, \fB\-r\fP, and \fB\-Q\fP, the cache will not be cleaned
after the access.
.P
The \fBless\fP example above won't work with options passed through
to \fIm4\fP (under \fB\-D\fP, \fB\-I\fP, \fB\-U\fP, or \fB\-o\fP)
as \fBless\fP doesn't understand \fBm4\fP options.  Code a simple
shell script to filter the command line for any programs might
want to run "under" \fI\*(PN\fP.
.\" yes, this is a clue, directed at you personally
.P
The \fB\-n\fP option outputs some extra markup to mimic what \fBm4\fP
might do with \fB\-D\fP, \fB\-I\fP, \fB\-U\fP, and \fB\-j\fP options.
This is not perfect as referenced to HXMD_U_MERGED won't work,
but it might work in other cases.
.P
The environment variable name \fBM4_PATH\fP is too close to the
one \fBm4\fP uses for its include path (\fBM4PATH\fP), which is is
also a bug in \fBhxmd\fP.
.P
The command-line compatibility with most of the options to \fBhxmd\fP
is not a bug, even if you think it is.

.SH AUTHOR
KS Braunsdorf, NonPlayer Character Guild
.br
hxmd span-me-not at-ksb dotty NPC Guild dot org.

.SH "SEE ALSO"
.hlm 0
sh(1), m4(1), hxmd(8l), hxmd(5l), mmsrc(8l), distrib(8l), xapply(1l)