codec, baseconv: Cleanup of the various binary encoding functions.

[mLib] / codec / bincode.1

diff --git a/codec/bincode.1 b/codec/bincode.1
new file mode 100644 (file)
index 0000000..7914f75
--- /dev/null
+++ b/codec/bincode.1
@@ -0,0 +1,107 @@
+.\" nroff
+.TH bincode 1 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+bincode \- binary-to-text encoding and decoding
+.SH SYNOPSIS
+.B bincode
+.RB [ \-de]
+.RB [ \-f
+.IR flags ]
+.RB [ \-i
+.IR indent ]
+.RB [ \-m
+.IR maxline ]
+.RB [ \-o
+.IR output ]
+.RI [ file ...]
+.SH DESCRIPTION
+The
+.B bincode
+program encodes binary data as plain text (suitable, for example, for
+use in email), and recovers binary data from its encoding.
+.PP
+The options are as follows.
+.TP
+.B "\-h, \-\-help"
+Print a help message to standard output and exit successfully.
+.TP
+.B "\-v, \-\-version"
+Print the program's version number to standard output and exit
+successfully.
+.TP
+.B "\-u, \-\-usage"
+Print a one-line usage summary to standard output and exit successfully.
+.TP
+.BI "\-d, \-\-decode"
+Read encoded data and write the result of decoding it.
+.TP
+.BI "\-e, \-\-encode"
+Read raw binary data and write the result of encoding.
+.TP
+.BI "\-f, \-\-flags=" flags
+Set encoding/decoding flags.  The
+.I flags
+are a list of comma-separated flag names, each preceded by an optional
+.RB ` + '
+to set the flag (the default) or
+.RB ` \- '
+to clear it.  The flag names are as listed in
+.BR codec (3),
+but in lower case, and without the
+.RB ` CDCF_ '
+prefix; e.g.,
+.B CDCF_IGNNEWL
+may be specified as
+.RB ` ignnewl '.
+This option may be repeated: the options are scanned left-to-right.  The
+only flag set by default is
+.RB ` ignnewl '.
+.TP
+.BI "\-i, \-\-indent=" indent
+Insert the
+.I indent
+string before each line.  The string may contain simple
+backslash-escapes:
+.RB ` \ea ',
+.RB ` \eb ',
+.RB ` \ef ',
+.RB ` \en ',
+.RB ` \er ',
+.RB ` \et ', and
+.RB ` \ev '
+respectively stand for alert, backspace, form-feed, newline, carriage
+return, and horizontal and vertical tab.  A backslash preceding any
+other character yields that character; hence, to include a backslash,
+write a double backslash.  The default is the empty string: i.e., just
+end each line with a newline character.
+.TP
+.BI "\-m, \-\-maxline=" maxline
+Set the maximum output line length to
+.I maxline
+when encoding.  The limit is ignored when decoding.  If
+.I maxline
+is zero, then no line splitting is performed.
+.TP
+.BI "\-o, \-\-output=" output
+Write the (encoded or decoded) output to
+.IR output .
+The default is to write to standard output.  On platforms where it makes
+a difference, the output file is opened in text mode when encoding, and
+in binary mode when decoding.
+.PP
+The input to be encoded or decoded is the concatenation of the specified
+.IR file s.
+If no files are listed, then standard input is read.  A
+.I file
+which is a single
+.RB ` \- '
+also means to read standard input.  On systems where it makes a
+difference, named files are read in binary mode when encoding and in
+text mode when decoding.
+.PP
+If an error is encountered, the output may be partially written.
+.SH "SEE ALSO"
+.BR codec (3).
+.SH "AUTHOR"
+Mark Wooding, <mdw@distorted.org.uk>
+