generate manual pages from Markdown instead of writing directly

13 files changed, 784 insertions, 309 deletions

diff --git a/asn1c/Makefile.am b/asn1c/Makefile.am
index a369de3f..d1527223 100644
--- a/asn1c/Makefile.am
+++ b/asn1c/Makefile.am
@@ -20,8 +20,6 @@ bin_PROGRAMS = asn1c unber enber
 
 noinst_HEADERS = sys-common.h
 
-dist_man1_MANS = asn1c.1 unber.1 enber.1
-
 dist_check_SCRIPTS = check-xxber.sh check-parsing.sh
 TESTS_ENVIRONMENT= top_srcdir=${top_srcdir}
 TESTS = $(dist_check_SCRIPTS)
diff --git a/asn1c/asn1c.1 b/asn1c/asn1c.1
deleted file mode 100644
index 5485cc98..00000000
--- a/asn1c/asn1c.1
+++ /dev/null
@@ -1,125 +0,0 @@
-.TH asn1c 1 "2014-10-23" "ASN.1 Compiler"
-.if n .ad l \" Turn off justifications
-.nh \" Turn off hyphenation; can damage formatting in technical documents.
-.SH NAME
-asn1c \(em the ASN.1 Compiler
-.SH SYNOPSIS
-asn1c [\fB\-E\fR [\fB-F\fR] | \fB\-P\fR | \fB\-R\fR]
-      [\fB\-S\fR\fIdir\fR] [\fB-X\fR]
-      [\fB\-W\fR\fIdebug-\fR...] [\fB\-f\fR\fIoption\fR] [\fB\-gen-\fR\fIoption\fR] [\fB\-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR}\fR]
-      [\fB\-print-\fR\fIoption\fR]
-      \fIinput-filenames\fR...
-.SH DESCRIPTION
-asn1c compiles ASN.1 specifications into a set of
-target language (C/C++) encoders and decoders for BER, DER, PER, XER
-and other encoding rules.
-.SH OPTIONS
-.SS Stage Selection Options
-.TP 4
-.B \-E
-Run the parsing stage only.
-Print the reconstructed ASN.1 text.
-.TP 4
-.B \-F
-Used together with
-.B \-E\c
-, instructs the compiler to stop after the ASN.1 syntax
-tree fixing stage and dump the reconstructed ASN.1 specification
-to the standard output.
-.TP 4
-.B \-P
-Dump the compiled output to the standard output instead of creating the
-target language files on disk.
-.TP 4
-.B \-R
-Restrict the compiler to generate only the ASN.1 tables,
-omitting the usual support code.
-.TP 4
-\fB\-S\fR \fIdirectory\fR
-Use the specified directory with ASN.1 skeleton files.
-.TP 4
-.B \-X
-Generate an XML DTD schema for the specified ASN.1 files.
-.SS Warning Options
-.TP 4
-.B \-Werror
-Treat warnings as errors; abort if any warning is produced.
-.TP 4
-.B \-Wdebug-lexer
-Enable lexer debugging during the ASN.1 parsing stage.
-.TP 4
-.B \-Wdebug-fixer
-Enable ASN.1 syntax tree fixer debugging during the fixing stage.
-.TP 4
-.B \-Wdebug-compiler
-Enable debugging during the actual compile time.
-.SS Language Options
-.TP 4
-.B \-fbless-SIZE
-Allow SIZE() constraint for INTEGER, ENUMERATED, and other types for which this
-constraint is normally prohibited by the standard.
-This is a violation of ASN.1 standard, and the compiler may
-fail to\ produce a meaningful code.
-.TP 4
-.B \-fcompound-names
-Using this option prevents name collisions in the target source code
-by using complex names for target language structures.
-(Name\ collisions may occur if the ASN.1 module reuses the same identifiers
-in multiple contexts).
-.TP 4
-.B \-findirect-choice
-When generating code for a CHOICE type, compile the CHOICE members as indirect
-pointers instead of declaring them inline.
-Consider using this option together with
-.B \-fno-include-deps
-to prevent circular references.
-.TP 4
-.B \-fincludes-quoted
-Generate #include lines in "double" instead of <angle> quotes.
-.TP 4
-.BI "\-fknown-extern-type="<name>
-Pretend the specified type is known.
-The compiler will assume the target language source files
-for the given type have been provided manually.
-.TP 4
-.B \-fline-refs
-Include ASN.1 module's line numbers in generated code comments.
-.TP 4
-.B \-fno-constraints
-Do not generate ASN.1 subtype constraint checking code.
-This may make a shorter executable.
-.TP 4
-.B \-fno-include-deps
-Do not generate courtesy #include lines for non-critical type dependencies.
-Helps prevent namespace collisions.
-.TP 4
-.B \-funnamed-unions
-Enable unnamed unions in the definitions of target language's structures.
-.TP 4
-.B \-fwide-types
-Use the unbounded size data types (INTEGER_t, ENUMERATED_t, REAL_t) by default,
-instead of the native machine's data types (long, double).
-.SS Codecs Generation Options
-.TP 4
-.B \-gen-PER
-Generate the Packed Encoding Rules (PER) support code.
-.TP 4
-.B \-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR}
-Create a PDU table for specified types, or discover Protocol Data Units automatically.
-In case of -pdu=\fBall\fR, all ASN.1 types defined in all modules will form a PDU table.
-In case of -pdu=\fBauto\fR, all types not referenced by any other type will form a PDU table.
-If\ \fIType\fR is an ASN.1 type identifier, it is added to a PDU table.
-The\ last form may be specified multiple times to add any number of PDUs.
-.SS Output Options
-.TP 4
-.B \-print-constraints
-When -EF are also specified, this option forces the compiler to explain
-its internal understanding of subtype constraints.
-.TP 4
-.B \-print-lines
-Generate "-- #line" comments in \fB-E\fR output.
-.SH SEE ALSO
-.TP 4
-\&\fIunber\fR\|(1), \&\fIenber\fR\|(1)
-.SH AUTHORS
-Lev Walkin <vlm@lionet.info>
diff --git a/asn1c/enber.1 b/asn1c/enber.1
deleted file mode 100644
index 999917eb..00000000
--- a/asn1c/enber.1
+++ /dev/null
@@ -1,53 +0,0 @@
-.TH enber 1 "2014-10-23" "unber counterpart"
-.if n .ad l \" Turn off justifications
-.nh \" Turn off hyphenation; can damage formatting in technical documents.
-.de Vb \" Verbatim begin.
-.sp
-.in +4
-.ft CW
-.nf
-..
-.de Ve \" Verbatim end.
-.ft R
-.in
-.fi
-..
-.SH NAME
-enber \(em Convert the unber XML output back into BER
-.SH SYNOPSIS
-enber [\fB\-n\fR] [\fB\-\fR] [\fIinput-filenames\fR...]
-.SH DESCRIPTION
-enber convers the XML-formatted files produced by \fIunber\fR\|(1) back into the BER format.
-A single dash denotes the standard input.
-.SH OPTIONS
-.TP 4
-\fB\-n\fR
-Disable input validation.
-By default, enber performs some basic validity checks
-against XML input.
-.SH EXAMPLES
-Decode a BER sequence and immediately encode it back
-.Vb
-unber \fB\-p\fR \fIfilename.ber\fR | enber \fB\-\fR > \fIreconstructed.ber\fR
-.Ve
-.SH FOOTNOTES
-This program does not attempt to perform full-fledged XML parsing.
-It is merely compatible with \fIunber\fR\|(1)'s output.
-In particular, XML style comments are not supported.
-A hash "\fB#\fR" or two dashes "\fB--\fR" following a whitespace is treated as a beginning of a comment line, which is ignored completely.
-Empty lines are ignored as well.
-.P
-The following example demostrates the use of comments:
-.Vb
-<C O="0" T="[1]" TL="2" V="2">
-    <I O="2" T="[1]" TL="2" V="Indefinite">
-    \fB--\fR </I O="4" T="[UNIVERSAL 0]" L="4">
-    \fB#\fR Do not terminate:
-    \fB#\fR the absence of end-of-content octets is intentional!
-</C O="6" T="[1]" L="6">
-.Ve
-.SH SEE ALSO
-.TP
-\fIunber\fR\|(1), \&\fIasn1c\fR\|(1)
-.SH AUTHORS
-Lev Walkin <vlm@lionet.info>
diff --git a/asn1c/unber.1 b/asn1c/unber.1
deleted file mode 100644
index e2725bd1..00000000
--- a/asn1c/unber.1
+++ /dev/null
@@ -1,128 +0,0 @@
-.TH unber 1 "2014-10-23" "ASN.1 BER Decoder"
-.if n .ad l \" Turn off justifications
-.nh \" Turn off hyphenation; can damage formatting in technical documents.
-.de Vb \" Verbatim.
-.sp
-.ft CW
-.nf
-..
-.de Vbi \" Verbatim, indented.
-.sp
-.ft CW
-.nf
-.in +4
-..
-.de Ve \" Verbatim end.
-.ft R
-.in
-.fi
-.sp
-..
-.SH NAME
-unber \(em the ASN.1 BER Decoder
-.SH SYNOPSIS
-unber [\fB\-1\fR] [\fB\-i\fRindent] [\fB\-m\fR] [\fB\-p\fR] [\fB\-s\fR\fIskip\fR] [\fB\-t\fR\fIhex\-string\fR] [\fB\-\fR] [\fIinput-filenames\fR...]
-.SH DESCRIPTION
-unber presents the internal structure of BER-encoded files as human readable text.
-A single dash denotes the standard input.
-.sp
-(The DER and CER formats are subsets of the BER and are also supported.)
-.SH OPTIONS
-.TP
-\fB\-1\fR
-Do \fInot\fR attempt to read the next BER structure after the first one.
-This may be useful if the input contains garbage past the single BER sequence.
-By default, unber continues decoding until the end of file (input stream).
-.TP
-\fB\-i\fR \fIindent\fR
-Use the specified number of spaces for output indentation.
-Default is 4 spaces.
-.TP
-\fB\-m\fR
-Generate shorter output while still preserving BER encoding information.
-.TP
-\fB\-p\fR
-Do \fInot\fR attempt pretty-printing of known ASN.1 types (BOOLEAN, INTEGER, OBJECT IDENTIFIER, etc).
-By default, some ASN.1 types are converted into the text representation.
-This option is required for \&\fIenber\fR\|(1).
-.TP
-\fB\-s\fR \fIskip\fR
-Ignore the first \fIskip\fR bytes in the input stream; useful for stripping off
-lower level protocol framing data.
-.TP
-\fB\-t\fR \fIhex-string\fR
-Interpret the hex-string as a sequence of hexadecimal values representing
-the start of BER TLV encoding.
-Print the human readable explanation.
-.SH XML FORMAT
-unber dumps the output in the regular XML format which preserves most of the
-information from the underlying binary encoding.
-.P
-The XML opening tag format is as follows:
-.Vb
-<\fBtform\fR O="\fBoff\fR" T="\fBtag\fR" TL="\fBtl_len\fR" V="{Indefinite|\fBv_len\fR}" [A="\fBtype\fR"] [\fBF\fR]>
-.Ve
-Where:
-.TP
-\fBtform\fR
-Encoding form the value is in: primitive ("P") or constructed ("C") or constructed with indefinite length ("I")
-.TP
-\fBoff\fR
-Offset of the encoded element in the unber input stream.
-.TP
-\fBtag\fR
-The tag class and value in human readable form.
-.TP
-\fBtl_len\fR
-The length of the TL (BER Tag and Length) encoding.
-.TP
-\fBv_len\fR
-The length of the value (V, encoded by the L), may be "Indefinite".
-.TP
-\fBtype\fR
-Likely name of the underlying ASN.1 type (for UNIVERSAL tags).
-.TP
-[\fBF\fR]
-Indicates that the value was reformatted (pretty-printed).
-This will never appear in the output produced using \fB\-p\fR command line option.
-.P
-Sample XML output:
-.Vb
-<I O="0" T="[UNIVERSAL 16]" TL="2" V="Indefinite" A="SEQUENCE">
-  <P O="2" T="[UNIVERSAL 19]" TL="2" V="2" A="PrintableString">US</P>
-  <C O="6" T="[UNIVERSAL 16]" TL="2" V="6" A="SEQUENCE">
-    <P O="8" T="[UNIVERSAL 2]" TL="2" V="4" A="INTEGER" F>832970823</P>
-  </C O="14" T="[UNIVERSAL 16]" A="SEQUENCE" L="8">
-</I O="14" T="[UNIVERSAL 0]" TL="2" L="16">
-.Ve
-.SH EXAMPLES
-Decode the given Tag/Length sequence specified in hexadecimal form:
-.Vbi
-unber  \fB\-t\fR "\fIbf 20\fR"
-.Ve
-Decode the DER file using two-spaces indentation:
-.Vbi
-unber  \fB\-i\fR \fI2\fR   \fIfilename.der\fR
-.Ve
-Decode the binary stream taken from the standard input:
-.Vbi
-cat \fIfilename.der\fR | unber \fB\-\fR
-.Ve
-Decode the binary stream and encode it back into an identical stream (see \&\fIenber\fR\|(1)):
-.Vbi
-cat \fIfilename.der\fR | unber \fB\-p\fR \fB\-\fR | enber \fB\-\fR > \fIfilename.ber\fR
-.Ve
-.SH FOOTNOTES
-The constructed XML output is not necessarily well-formed.
-.P
-When indefinite length encoding is being used, the BER sequence, which is not
-terminated with the end-of-content octets, will cause the terminating \fB</I>\fR
-XML tag to disappear.
-Thus, invalid BER framing directly causes invalid XML output.
-.P
-The \fIenber\fR\|(1) utility understands such XML correctly.
-.SH SEE ALSO
-.TP
-\fIenber\fR\|(1), \fIasn1c\fR\|(1)
-.SH AUTHORS
-Lev Walkin <vlm@lionet.info>
diff --git a/configure.ac b/configure.ac
index 2698265a..478e0fe5 100644
--- a/configure.ac
+++ b/configure.ac
@@ -111,6 +111,10 @@ AC_CHECK_FUNCS(timegm)
 AC_CHECK_DECLS(alloca strcasecmp)
 AC_TRY_LINK_FUNC([symlink],[AC_DEFINE([HAVE_SYMLINK], 1, [Define to 1 if you have the symlink function.])])
 
+dnl Use pandoc to generate manual pages.
+AC_PATH_PROG([PANDOC], pandoc)
+AM_CONDITIONAL([HAVE_PANDOC], [test -n "$PANDOC"])
+
 AC_OUTPUT(				\
 skeletons/tests/Makefile		\
 libasn1compiler/Makefile		\
@@ -121,6 +125,7 @@ libasn1fix/Makefile			\
 doc/docsrc/Makefile			\
 skeletons/Makefile			\
 examples/Makefile			\
+doc/man/Makefile			\
 asn1c/Makefile				\
 doc/Makefile				\
 asn1c.spec				\
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9582917c..aa462b7d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,5 +1,5 @@
 
-SUBDIRS = docsrc
+SUBDIRS = docsrc man
 
 docsdir = $(datadir)/doc/asn1c
 
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
new file mode 100644
index 00000000..1035ff96
--- /dev/null
+++ b/doc/man/Makefile.am
@@ -0,0 +1,16 @@
+
+dist_man1_MANS = asn1c.1 unber.1 enber.1
+
+if HAVE_PANDOC
+
+PANDOC_OPTIONS= --from markdown --to man        \
+		--variable header="Version ${VERSION}"  \
+		--variable adjusting:l                  \
+		--variable hyphenate:""                 \
+		--standalone
+
+%.1: %.man.md
+	${PANDOC} ${PANDOC_OPTIONS} -o $@ $<
+
+endif
+
diff --git a/doc/man/asn1c.1 b/doc/man/asn1c.1
new file mode 100644
index 00000000..54c23373
--- /dev/null
+++ b/doc/man/asn1c.1
@@ -0,0 +1,199 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.ad l
+.TH "asn1c" "1" "2016\-01\-23" "ASN.1 Compiler" "Version 0.9.28"
+.nh \" Turn off hyphenation by default.
+.SH NAME
+.PP
+asn1c \-\- the ASN.1 Compiler
+.SH SYNOPSIS
+.PP
+asn1c [\f[B]\-E\f[] [\f[B]\-F\f[]] | \f[B]\-P\f[] | \f[B]\-R\f[]]
+.PD 0
+.P
+.PD
+[\f[B]\-S\f[]\f[I]dir\f[]] [\f[B]\-X\f[]]
+.PD 0
+.P
+.PD
+[\f[B]\-W\f[]\f[I]debug\-\f[]...] [\f[B]\-f\f[]\f[I]option\f[]]
+[\f[B]\-gen\-\f[]\f[I]option\f[]]
+[\f[B]\-pdu\f[]={\f[B]all\f[]|\f[B]auto\f[]|\f[I]Type\f[]}]
+.PD 0
+.P
+.PD
+[\f[B]\-print\-\f[]\f[I]option\f[]]
+.PD 0
+.P
+.PD
+\f[I]input\-filenames\f[]...
+.SH DESCRIPTION
+.PP
+asn1c compiles ASN.1 specifications into a set of target language
+(C/C++) encoders and decoders for BER, DER, PER, XER and other encoding
+rules.
+.SH OPTIONS
+.SS Stage Selection Options
+.TP
+.B \-E
+Run the parsing stage only.
+Print the reconstructed ASN.1 text.
+.RS
+.RE
+.TP
+.B \-F
+Used together with \f[B]\-E\f[], instructs the compiler to stop after
+the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
+specification to the standard output.
+.RS
+.RE
+.TP
+.B \-P
+Dump the compiled output to the standard output instead of creating the
+target language files on disk.
+.RS
+.RE
+.TP
+.B \-R
+Restrict the compiler to generate only the ASN.1 tables, omitting the
+usual support code.
+.RS
+.RE
+.TP
+.B \-S \f[I]directory\f[]
+Use the specified directory with ASN.1 skeleton files.
+.RS
+.RE
+.TP
+.B \-X
+Generate an XML DTD schema for the specified ASN.1 files.
+.RS
+.RE
+.SS Warning Options
+.TP
+.B \-Werror
+Treat warnings as errors; abort if any warning is produced.
+.RS
+.RE
+.TP
+.B \-Wdebug\-lexer
+Enable lexer debugging during the ASN.1 parsing stage.
+.RS
+.RE
+.TP
+.B \-Wdebug\-fixer
+Enable ASN.1 syntax tree fixer debugging during the fixing stage.
+.RS
+.RE
+.TP
+.B \-Wdebug\-compiler
+Enable debugging during the actual compile time.
+.RS
+.RE
+.SS Language Options
+.TP
+.B \-fbless\-SIZE
+Allow \f[C]SIZE()\f[] constraint for \f[C]INTEGER\f[],
+\f[C]ENUMERATED\f[], and other types for which this constraint is
+normally prohibited by the standard.
+This is a violation of ASN.1 standard, and the compiler may fail to
+produce a meaningful code.
+.RS
+.RE
+.TP
+.B \-fcompound\-names
+Using this option prevents name collisions in the target source code by
+using complex names for target language structures.
+(Name collisions may occur if the ASN.1 module reuses the same
+identifiers in multiple contexts).
+.RS
+.RE
+.TP
+.B \-findirect\-choice
+When generating code for a \f[C]CHOICE\f[] type, compile the
+\f[C]CHOICE\f[] members as indirect pointers instead of declaring them
+inline.
+Consider using this option together with \f[B]\-fno\-include\-deps\f[]
+to prevent circular references.
+.RS
+.RE
+.TP
+.B \-fincludes\-quoted
+Refer to header files in \f[C]#include\f[]s using
+\f[B]"\f[]double\f[B]"\f[] instead of \f[B]<\f[]angle\f[B]>\f[] quotes.
+.RS
+.RE
+.TP
+.B \-fknown\-extern\-type=\f[I]name\f[]
+Pretend the specified type is known.
+The compiler will assume the target language source files for the given
+type have been provided manually.
+.RS
+.RE
+.TP
+.B \-fline\-refs
+Include ASN.1 module\[aq]s line numbers in generated code comments.
+.RS
+.RE
+.TP
+.B \-fno\-constraints
+Do not generate ASN.1 subtype constraint checking code.
+This may make a shorter executable.
+.RS
+.RE
+.TP
+.B \-fno\-include\-deps
+Do not generate courtesy #include lines for non\-critical type
+dependencies.
+Helps prevent namespace collisions.
+.RS
+.RE
+.TP
+.B \-funnamed\-unions
+Enable unnamed unions in the definitions of target language\[aq]s
+structures.
+.RS
+.RE
+.TP
+.B \-fwide\-types
+Use the unbounded size data types (\f[C]INTEGER_t\f[],
+\f[C]ENUMERATED_t\f[], \f[C]REAL_t\f[]) by default, instead of using the
+native machine\[aq]s data types (long, double).
+.RS
+.RE
+.SS Codecs Generation Options
+.TP
+.B \-gen\-PER
+Generate the Packed Encoding Rules (PER) support code.
+.RS
+.RE
+.TP
+.B \-pdu={all|auto|\f[I]Type\f[]}
+Create a PDU table for specified types, or discover Protocol Data Units
+automatically.
+In case of \f[B]\-pdu=all\f[], all ASN.1 types defined in all modules
+will form a PDU table.
+In case of \f[B]\-pdu=auto\f[], all types not referenced by any other
+type will form a PDU table.
+If \f[I]Type\f[] is an ASN.1 type identifier, the identifier is added to
+the generated PDU table.
+The last form may be specified multiple times to add any number of PDUs.
+.RS
+.RE
+.SS Output Options
+.TP
+.B \-print\-constraints
+When \f[B]\-EF\f[] options are also specified, this option forces the
+compiler to explain its internal understanding of subtype constraints.
+.RS
+.RE
+.TP
+.B \-print\-lines
+Generate "\f[C]\-\-\ #line\f[]" comments in \f[B]\-E\f[] output.
+.RS
+.RE
+.SH SEE ALSO
+.PP
+\f[C]unber\f[](1), \f[C]enber\f[](1).
+.SH AUTHORS
+Lev Walkin <vlm@lionet.info>.
diff --git a/doc/man/asn1c.man.md b/doc/man/asn1c.man.md
new file mode 100644
index 00000000..afec71f9
--- /dev/null
+++ b/doc/man/asn1c.man.md
@@ -0,0 +1,140 @@
+% asn1c(1) ASN.1 Compiler
+% Lev Walkin <vlm@lionet.info>
+% 2016-01-23
+
+# NAME
+
+asn1c -- the ASN.1 Compiler
+
+# SYNOPSIS
+
+asn1c [**-E** [**-F**] | **-P** | **-R**] \
+      [**-S***dir*] [**-X**] \
+      [**-W***debug-*...] [**-f***option*] [**-gen-***option*] 
+      [**-pdu**={**all**|**auto**|*Type*}] \
+      [**-print-***option*] \
+      *input-filenames*...
+
+# DESCRIPTION
+
+asn1c compiles ASN.1 specifications into a set of
+target language (C/C++) encoders and decoders for BER, DER, PER, XER
+and other encoding rules.
+
+# OPTIONS
+
+## Stage Selection Options
+
+-E
+:   Run the parsing stage only. Print the reconstructed ASN.1 text.
+
+-F
+:   Used together with **-E**,
+    instructs the compiler to stop after the ASN.1 syntax
+    tree fixing stage and dump the reconstructed ASN.1 specification
+    to the standard output.
+
+-P
+:   Dump the compiled output to the standard output instead of creating the
+    target language files on disk.
+
+-R
+:   Restrict the compiler to generate only the ASN.1 tables,
+    omitting the usual support code.
+
+-S *directory*
+:   Use the specified directory with ASN.1 skeleton files.
+
+-X
+:   Generate an XML DTD schema for the specified ASN.1 files.
+
+## Warning Options
+
+-Werror
+:   Treat warnings as errors; abort if any warning is produced.
+
+-Wdebug-lexer
+:   Enable lexer debugging during the ASN.1 parsing stage.
+
+-Wdebug-fixer
+:   Enable ASN.1 syntax tree fixer debugging during the fixing stage.
+
+-Wdebug-compiler
+:   Enable debugging during the actual compile time.
+
+## Language Options
+
+-fbless-SIZE
+:   Allow `SIZE()` constraint for `INTEGER`, `ENUMERATED`,
+    and other types for which this constraint is normally prohibited
+    by the standard.
+    This is a violation of ASN.1 standard, and the compiler may
+    fail to produce a meaningful code.
+
+-fcompound-names
+:   Using this option prevents name collisions in the target source code
+    by using complex names for target language structures.
+    (Name collisions may occur if the ASN.1 module reuses the same identifiers
+    in multiple contexts).
+
+-findirect-choice
+:   When generating code for a `CHOICE` type, compile the `CHOICE` members
+    as indirect pointers instead of declaring them inline.
+    Consider using this option together with **-fno-include-deps**
+    to prevent circular references.
+
+-fincludes-quoted
+:   Refer to header files in `#include`s using **"**double**"** instead of **\<**angle**>** quotes.
+
+-fknown-extern-type=*name*
+:   Pretend the specified type is known.
+    The compiler will assume the target language source files
+    for the given type have been provided manually.
+
+-fline-refs
+:   Include ASN.1 module's line numbers in generated code comments.
+
+-fno-constraints
+:   Do not generate ASN.1 subtype constraint checking code.
+    This may make a shorter executable.
+
+-fno-include-deps
+:   Do not generate courtesy #include lines for non-critical type dependencies.
+    Helps prevent namespace collisions.
+
+-funnamed-unions
+:   Enable unnamed unions in the definitions of target language's structures.
+
+-fwide-types
+:   Use the unbounded size data types (`INTEGER_t`, `ENUMERATED_t`, `REAL_t`)
+    by default, instead of using the native machine's data types (long, double).
+
+## Codecs Generation Options
+
+-gen-PER
+:   Generate the Packed Encoding Rules (PER) support code.
+
+-pdu={all|auto|*Type*}
+:   Create a PDU table for specified types, or discover Protocol Data Units
+    automatically. In case of **-pdu=all**,
+    all ASN.1 types defined in all modules will form a PDU table.
+    In case of **-pdu=auto**, all types not referenced by any other type will
+    form a PDU table.
+    If *Type* is an ASN.1 type identifier, the identifier is added to
+    the generated PDU table.
+    The last form may be specified multiple times to add any number of PDUs.
+
+## Output Options
+
+-print-constraints
+:   When **-EF** options are also specified,
+    this option forces the compiler to explain its internal understanding
+    of subtype constraints.
+
+-print-lines
+:   Generate "`-- #line`" comments in **-E** output.
+
+# SEE ALSO
+
+`unber`(1), `enber`(1).
+
diff --git a/doc/man/enber.1 b/doc/man/enber.1
new file mode 100644
index 00000000..827c211b
--- /dev/null
+++ b/doc/man/enber.1
@@ -0,0 +1,71 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.ad l
+.TH "enber" "1" "2016\-01\-23" "unber(1) counterpart" "Version 0.9.28"
+.nh \" Turn off hyphenation by default.
+.SH NAME
+.PP
+enber \-\- Convert the unber XML output back into BER
+.SH SYNOPSIS
+.PP
+enber [\f[B]\-n\f[]] [\f[B]\-\f[]] [\f[I]input\-filenames\f[]...]
+.SH DESCRIPTION
+.PP
+enber converts the XML\-formatted files produced by \f[C]unber\f[](1)
+back into the BER format.
+A single dash denotes the standard input.
+.SH OPTIONS
+.TP
+.B \-n
+Disable input validation.
+By default, enber performs some basic validity checks against XML input.
+.RS
+.RE
+.SH EXAMPLES
+.PP
+Decode a BER sequence and immediately encode it back
+.RS
+.PP
+unber \f[B]\-p\f[] \f[I]filename.ber\f[] | enber \f[B]\-\f[] >
+\f[I]reconstructed.ber\f[]
+.RE
+.SH FOOTNOTES
+.PP
+This program does not attempt to perform full\-fledged XML parsing.
+It is merely compatible with \f[C]unber\f[](1)\[aq]s output.
+In particular, the XML style comments are not supported.
+A hash "\f[B]#\f[]" or two dashes "\f[B]\-\-\f[]" following a whitespace
+is treated as a beginning of a comment line, which is ignored
+completely.
+Empty lines are ignored as well.
+.PP
+The following example \f[C]enber\f[](1) input demostrates the use of
+comments:
+.PP
+<C O="0" T="[1]" TL="2" V="2">
+.PD 0
+.P
+.PD
+\ \ \ \ <I O="2" T="[1]" TL="2" V="Indefinite">
+.PD 0
+.P
+.PD
+\ \ \ \ \f[B]\-\-\f[] </I O="4" T="[UNIVERSAL 0]" L="4">
+.PD 0
+.P
+.PD
+\ \ \ \ \f[B]#\f[] Do not terminate:
+.PD 0
+.P
+.PD
+\ \ \ \ \f[B]#\f[] the absence of end\-of\-content octets is
+intentional!
+.PD 0
+.P
+.PD
+</C O="6" T="[1]" L="6">
+.SH SEE ALSO
+.PP
+\f[C]unber\f[](1), \f[C]asn1c\f[](1).
+.SH AUTHORS
+Lev Walkin <vlm@lionet.info>.
diff --git a/doc/man/enber.man.md b/doc/man/enber.man.md
new file mode 100644
index 00000000..2bdb0369
--- /dev/null
+++ b/doc/man/enber.man.md
@@ -0,0 +1,50 @@
+% enber(1) unber(1) counterpart
+% Lev Walkin <vlm@lionet.info>
+% 2016-01-23
+
+# NAME
+
+enber -- Convert the unber XML output back into BER
+
+# SYNOPSIS
+
+enber [**-n**] [**-**] [*input-filenames*...]
+
+# DESCRIPTION
+
+enber converts the XML-formatted files produced by `unber`(1) back into the BER format.
+A single dash denotes the standard input.
+
+# OPTIONS
+
+-n
+:   Disable input validation.
+By default, enber performs some basic validity checks
+against XML input.
+
+# EXAMPLES
+
+Decode a BER sequence and immediately encode it back
+
+> unber **-p** *filename.ber* | enber **-** > *reconstructed.ber*
+
+# FOOTNOTES
+
+This program does not attempt to perform full-fledged XML parsing.
+It is merely compatible with `unber`(1)'s output.
+In particular, the XML style comments are not supported.
+A hash "**#**" or two dashes "**--**" following a whitespace is treated as a beginning of a comment line, which is ignored completely.
+Empty lines are ignored as well.
+
+The following example `enber`(1) input demostrates the use of comments:
+
+| \<C O="0" T="[1]" TL="2" V="2">
+|     \<I O="2" T="[1]" TL="2" V="Indefinite">
+|     **--** \</I O="4" T="[UNIVERSAL 0]" L="4">
+|     **#** Do not terminate:
+|     **#** the absence of end-of-content octets is intentional!
+| \</C O="6" T="[1]" L="6">
+
+# SEE ALSO
+
+`unber`(1), `asn1c`(1).
diff --git a/doc/man/unber.1 b/doc/man/unber.1
new file mode 100644
index 00000000..8f787b40
--- /dev/null
+++ b/doc/man/unber.1
@@ -0,0 +1,181 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.ad l
+.TH "unber" "1" "2016\-01\-23" "ASN.1 BER Decoder" "Version 0.9.28"
+.nh \" Turn off hyphenation by default.
+.SH NAME
+.PP
+unber \-\- the ASN.1 BER Decoder
+.SH SYNOPSIS
+.PP
+unber [\f[B]\-1\f[]] [\f[B]\-i\f[]\f[I]indent\f[]] [\f[B]\-m\f[]]
+[\f[B]\-p\f[]] [\f[B]\-s\f[]\f[I]skip\f[]]
+[\f[B]\-t\f[]\f[I]hex\-string\f[]] [\f[B]\-\f[]]
+[\f[I]input\-filenames\f[]...]
+.SH DESCRIPTION
+.PP
+unber presents the internal structure of BER\-encoded files as a human
+readable text.
+A single dash denotes the standard input.
+.PP
+(The DER and CER formats are subsets of the BER and are also supported.)
+.SH OPTIONS
+.TP
+.B \-1
+Do \f[I]not\f[] attempt to read the next BER structure after the first
+one.
+This may be useful if the input contains garbage past the single BER
+sequence.
+By default, unber continues decoding until the end of file (input
+stream).
+.RS
+.RE
+.TP
+.B \-i \f[I]indent\f[]
+Use the specified number of spaces for output indentation.
+Default is 4 spaces.
+.RS
+.RE
+.TP
+.B \-m
+Generate shorter output while still preserving BER encoding information.
+.RS
+.RE
+.TP
+.B \-p
+Do \f[I]not\f[] attempt to pretty\-print known ASN.1 types
+(\f[C]BOOLEAN\f[], \f[C]INTEGER\f[], \f[C]OBJECT\ IDENTIFIER\f[], etc).
+By default, some ASN.1 types are converted into the text representation.
+.RS
+.PP
+This option is required if the \f[C]unber\f[](1) output is used as an
+input to \f[C]enber\f[](1).
+.RE
+.TP
+.B \-s \f[I]skip\f[]
+Ignore the first \f[I]skip\f[] bytes in the input stream; useful for
+stripping off lower level protocol framing data.
+.RS
+.RE
+.TP
+.B \-t \f[I]hex\-string\f[]
+Interpret the hex\-string as a sequence of hexadecimal values
+representing the start of BER TLV encoding.
+Print the human readable explanation.
+.RS
+.RE
+.SH XML FORMAT
+.PP
+unber dumps the output in the regular XML format which preserves most of
+the information from the underlying binary encoding.
+.PP
+The XML opening tag format is as follows:
+.PP
+<\f[B]tform\f[] O="\f[B]off\f[]" T="\f[B]tag\f[]" TL="\f[B]t_len\f[]"
+V="{Indefinite|\f[B]v_len\f[]}" [A="\f[B]type\f[]"] [\f[B]F\f[]]>
+.PP
+Where:
+.TP
+.B \f[B]tform\f[]
+Encoding form the value is in: primitive ("P") or constructed ("C") or
+constructed with indefinite length ("I")
+.RS
+.RE
+.TP
+.B \f[B]off\f[]
+Offset of the encoded element in the unber input stream.
+.RS
+.RE
+.TP
+.B \f[B]tag\f[]
+The tag class and value in human readable form.
+.RS
+.RE
+.TP
+.B \f[B]t_len\f[]
+The length of the TL (BER Tag and Length) encoding.
+.RS
+.RE
+.TP
+.B \f[B]v_len\f[]
+The length of the value (V, encoded by the L), may be "Indefinite".
+.RS
+.RE
+.TP
+.B \f[B]type\f[]
+Likely name of the underlying ASN.1 type (for UNIVERSAL tags).
+.RS
+.RE
+.TP
+.B [\f[B]F\f[]]
+Indicates that the value was reformatted (pretty\-printed).
+This will never appear in the output produced using the \f[B]\-p\f[]
+command line option.
+.RS
+.RE
+.SS Example XML output:
+.PP
+<I O="0" T="[UNIVERSAL 16]" TL="2" V="Indefinite" A="SEQUENCE">
+.PD 0
+.P
+.PD
+\ <P O="2" T="[UNIVERSAL 19]" TL="2" V="2" A="PrintableString">US</P>
+.PD 0
+.P
+.PD
+\ \ <C O="6" T="[UNIVERSAL 16]" TL="2" V="6" A="SEQUENCE">
+.PD 0
+.P
+.PD
+\ \ \ \ <P O="8" T="[UNIVERSAL 2]" TL="2" V="4" A="INTEGER"
+F>832970823</P>
+.PD 0
+.P
+.PD
+\ \ </C O="14" T="[UNIVERSAL 16]" A="SEQUENCE" L="8">
+.PD 0
+.P
+.PD
+</I O="14" T="[UNIVERSAL 0]" TL="2" L="16">
+.SH EXAMPLES
+.PP
+Decode the given Tag/Length sequence specified in hexadecimal form:
+.RS
+.PP
+unber\  \f[B]\-t\f[] "\f[I]bf 20\f[]"
+.RE
+.PP
+Decode the DER file using two\-spaces indentation:
+.RS
+.PP
+unber\  \f[B]\-i\f[] \f[I]2\f[]\  \f[I]filename.der\f[]
+.RE
+.PP
+Decode the binary stream taken from the standard input:
+.RS
+.PP
+cat \f[I]filename.der\f[] | unber \f[B]\-\f[]
+.RE
+.PP
+Decode the binary stream and encode it back into an identical stream
+(see \f[C]enber\f[](1)):
+.RS
+.PP
+cat \f[I]filename.der\f[] | unber \f[B]\-p\f[] \f[B]\-\f[] | enber
+\f[B]\-\f[] > \f[I]filename.ber\f[]
+.RE
+.SH FOOTNOTES
+.PP
+The constructed XML output is not necessarily well\-formed.
+.PP
+When indefinite length encoding is being used, the BER sequence which is
+not terminated with the end\-of\-content octets will cause the
+terminating \f[B]</I>\f[] XML tag to disappear.
+Thus, invalid BER framing directly causes invalid XML output.
+.PP
+The \f[C]enber\f[](1) utility understands such XML correctly.
+.SH SEE ALSO
+.PP
+\f[C]enber\f[](1), \f[C]asn1c\f[](1).
+.SH AUTHORS
+Lev Walkin <vlm@lionet.info>.
diff --git a/doc/man/unber.man.md b/doc/man/unber.man.md
new file mode 100644
index 00000000..b110eb86
--- /dev/null
+++ b/doc/man/unber.man.md
@@ -0,0 +1,121 @@
+% unber(1) ASN.1 BER Decoder
+% Lev Walkin <vlm@lionet.info>
+% 2016-01-23
+
+# NAME
+
+unber -- the ASN.1 BER Decoder
+
+# SYNOPSIS
+
+unber [**-1**] [**-i***indent*] [**-m**] [**-p**] [**-s***skip*] [**-t***hex-string*] [**-**] [*input-filenames*...]
+
+# DESCRIPTION
+
+unber presents the internal structure of BER-encoded files as a human readable text.
+A single dash denotes the standard input.
+
+(The DER and CER formats are subsets of the BER and are also supported.)
+
+# OPTIONS
+
+-1
+:   Do *not* attempt to read the next BER structure after the first one.
+    This may be useful if the input contains garbage past the single BER sequence.
+    By default, unber continues decoding until the end of file (input stream).
+
+-i *indent*
+:   Use the specified number of spaces for output indentation.
+    Default is 4 spaces.
+
+-m
+:   Generate shorter output while still preserving BER encoding information.
+
+-p
+:   Do *not* attempt to pretty-print known ASN.1 types (`BOOLEAN`, `INTEGER`, `OBJECT IDENTIFIER`, etc).
+    By default, some ASN.1 types are converted into the text representation.
+
+    This option is required if the `unber`(1) output is used as an input to `enber`(1).
+
+-s *skip*
+:   Ignore the first *skip* bytes in the input stream;
+    useful for stripping off lower level protocol framing data.
+
+-t *hex-string*
+:   Interpret the hex-string as a sequence of hexadecimal values representing
+    the start of BER TLV encoding.
+    Print the human readable explanation.
+
+# XML FORMAT
+unber dumps the output in the regular XML format which preserves most of the
+information from the underlying binary encoding.
+
+The XML opening tag format is as follows:
+
+<**tform** O="**off**" T="**tag**" TL="**t_len**" V="{Indefinite|**v_len**}" [A="**type**"] [**F**]>
+
+Where:
+
+**tform**
+:   Encoding form the value is in: primitive ("P") or constructed ("C") or constructed with indefinite length ("I")
+
+**off**
+:   Offset of the encoded element in the unber input stream.
+
+**tag**
+:   The tag class and value in human readable form.
+
+**t_len**
+:   The length of the TL (BER Tag and Length) encoding.
+
+**v_len**
+:   The length of the value (V, encoded by the L), may be "Indefinite".
+
+**type**
+:   Likely name of the underlying ASN.1 type (for UNIVERSAL tags).
+
+[**F**]
+:   Indicates that the value was reformatted (pretty-printed).
+This will never appear in the output produced using the **-p**
+command line option.
+
+## Example XML output:
+
+| \<I O="0" T="[UNIVERSAL 16]" TL="2" V="Indefinite" A="SEQUENCE">
+|  \<P O="2" T="[UNIVERSAL 19]" TL="2" V="2" A="PrintableString">US\</P>
+|   \<C O="6" T="[UNIVERSAL 16]" TL="2" V="6" A="SEQUENCE">
+|     \<P O="8" T="[UNIVERSAL 2]" TL="2" V="4" A="INTEGER" F>832970823\</P>
+|   \</C O="14" T="[UNIVERSAL 16]" A="SEQUENCE" L="8">
+| \</I O="14" T="[UNIVERSAL 0]" TL="2" L="16">
+
+# EXAMPLES
+
+Decode the given Tag/Length sequence specified in hexadecimal form:
+
+> unber\  **-t** "*bf 20*"
+
+Decode the DER file using two-spaces indentation:
+
+> unber\  **-i** *2*\   *filename.der*
+
+Decode the binary stream taken from the standard input:
+
+> cat *filename.der* | unber **-**
+
+Decode the binary stream and encode it back into an identical stream (see `enber`(1)):
+
+> cat *filename.der* | unber **-p** **-** | enber **-** > *filename.ber*
+
+# FOOTNOTES
+The constructed XML output is not necessarily well-formed.
+
+When indefinite length encoding is being used, the BER sequence which is not
+terminated with the end-of-content octets will cause the terminating **\</I>**
+XML tag to disappear.
+Thus, invalid BER framing directly causes invalid XML output.
+
+The `enber`(1) utility understands such XML correctly.
+
+# SEE ALSO
+
+`enber`(1), `asn1c`(1).