- * fmt_compile.c -- "compile" format strings for fmt_scan
- *
- * This code is Copyright (c) 2002, by the authors of nmh. See the
- * COPYRIGHT file in the root directory of the nmh distribution for
- * complete copyright information.
- */
+** fmt_compile.c -- "compile" format strings for fmt_scan
+**
+** This code is Copyright (c) 2002, by the authors of nmh. See the
+** COPYRIGHT file in the root directory of the nmh distribution for
+** complete copyright information.
+**
+** This code compiles the format strings (documented in mh-format(5)) into
+** an internal form to be later processed by fmt_scan.c.
+**
+** What happens here is that the format strings are parsed and an array
+** of struct format structures are returned. Each format structure is
+** a single operation interpreted by the the routines in fmt_scan.c.
+**
+** There is a NOT a one-to-one correspondence between format strings and
+** format instructions; some functions have side effects that can result
+** in multiple instructions being generated. The exact list of instructions
+** generated by a format string can be seem with the nmh fmtdump utility.
+**
+** A list of format instructions can be found in fmt_compile.h.
+**
+** If you wish to add a new function, you will need to do the following
+** things:
+**
+** - Add a new instruction to the list of instructions in fmt_compile.h.
+** Note that test instructions (starting with FT_IF_S_NULL) have special
+** handling, so if you are NOT writing a test function then you need
+** to insert it into the list before that _and_ bump all of the
+** following instruction numbers.
+**
+** - Add the function name to the functable[] array below, and write any
+** special code that your function may require in terms of parsing
+** (it very well may not need anything).
+**
+** - Add the code in fmt_scan.c to handle your new function.
+**
+** - Document the new function in the mh-format(5) man page.
+**
+*/