diff --git a/.gitignore b/.gitignore
index f085b666..847752f3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,7 +16,7 @@ Makefile
aclocal.m4
*.cache/
configure
-config.*
+/config.*
# should be added using autoreconf -i
/tools/install-sh
diff --git a/configure.ac b/configure.ac
index 59ad044d..a4551fad 100644
--- a/configure.ac
+++ b/configure.ac
@@ -60,7 +60,17 @@ AC_SUBST(DSLC_CLASSPATH, [$DSLC_CLASSPATH])
AC_SUBST([AUTOGENERATED],
["THIS FILE IS AUTOGENERATED! DO NOT MODIFY! See *.in."])
-AC_CONFIG_FILES([Makefile doc/Makefile src/init.xsl VERSION])
+# Documentation
+set_devnotes='@set DEVNOTES'
+AC_ARG_ENABLE(
+ [devnotes],
+ [AS_HELP_STRING([--enable-devnotes],
+ [include notes in manual for TAME developers (enabled by default)])],
+ [test "x$enableval" != xno || set_devnotes="@c $set_devnotes"])
+
+AC_SUBST([SET_DEVNOTES], [$set_devnotes])
+
+AC_CONFIG_FILES([Makefile doc/Makefile doc/config.texi src/init.xsl VERSION])
AC_CONFIG_FILES([bin/dslc],
[chmod +x bin/dslc])
diff --git a/doc/.gitignore b/doc/.gitignore
index 14d345e2..cc458a8c 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -20,3 +20,6 @@ version.texi
/Makefile.in
/Makefile
+# generated from *.in
+/config.texi
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 93125f27..bdd3ce7d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -27,7 +27,8 @@ stylesheets := $(shell find "$(path_src)" \
stexi := $(stylesheets:.xsl=.texi)
info_TEXINFOS = tame.texi
-tame_TEXINFOS = about.texi preproc.texi license.texi $(stexi) tame.css
+tame_TEXINFOS = about.texi macros.texi preproc.texi license.texi \
+ config.texi $(stexi) tame.css
MAKEINFOHTML=$(MAKEINFO) --html --css-include tame.css
diff --git a/doc/config.texi.in b/doc/config.texi.in
new file mode 100644
index 00000000..f6285283
--- /dev/null
+++ b/doc/config.texi.in
@@ -0,0 +1,4 @@
+@c Manual configuration
+
+@c whether to include notes for TAME developers
+@SET_DEVNOTES@
diff --git a/doc/macros.texi b/doc/macros.texi
new file mode 100644
index 00000000..436d6925
--- /dev/null
+++ b/doc/macros.texi
@@ -0,0 +1,197 @@
+@c This document is part of the TAME manual.
+@c Copyright (C) 2015, 2016, 2018, 2019 R-T Specialty, LLC.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled ``GNU Free
+@c Documentation License''.
+
+@macro tame{}
+TAME
+@end macro
+
+@macro ttref{ref}
+@ref{\ref\,,@code{\ref\}}
+@end macro
+
+@macro proof{str}
+@sc{Proof:} \str\ @qed
+@end macro
+
+@macro qed{}
+∎
+@end macro
+
+@macro pkgns{node}
+@code{lv:\node\}
+@end macro
+
+
+@c unicode CONSTRUCTION SIGN
+@macro constructionsign
+🚧
+@end macro
+
+
+@c insert appropriate em dash for mode
+@ifnottex
+@macro mdash
+@inlinefmtifelse{html, @inlineraw{html,—}, —}
+@end macro
+@end ifnottex
+
+@c the macro for TeX for some reason always seems to be followed
+@c by a space when applied; #1 consumes it and re-adds if it's
+@c not empty
+@tex
+\gdef\mdash#1{%
+ ---%
+ \def\next{#1}%
+ \ifx\next\empty\relax\else#1\fi%
+}
+@end tex
+
+
+@c inline documentation notice for some sort of quality
+@c improvement or warning
+@macro noticestart{type}
+@html
+
+@end html
+@end macro
+
+@macro noticeend{}
+@html
+
+@end html
+@end macro
+
+
+@c vanilla notice
+@macro notice{text}
+@noticestart{}
+@emph{\text\}
+@noticeend
+@end macro
+
+
+@c notice for developers of liza
+@macro devnotice{text}
+@ifset DEVNOTES
+ @noticestart{devnotice}
+ @emph{\text\}
+ @noticeend
+@end ifset
+@end macro
+
+@c implementation note for developers of liza
+@macro devnote{text}
+@ifset DEVNOTES
+ @noticestart{devnote}
+ \text\
+ @noticeend
+@end ifset
+@end macro
+
+@c documentation TODO
+@macro todo{text}
+@devnotice{TODO: \text\}
+@end macro
+
+
+@c indicate that help is needed to produce docs
+@macro helpwanted{}
+@cindex TODO, Missing Docs
+@dnindex Missing Docs
+@notice{There isn't much here yet. Maybe you can help?}
+@end macro
+
+
+@c maintenance note for developers
+@c
+@c N.B. use @maintstart and @maintend manually if using multiple
+@c paragraphs otherwise PDF output (TeX) breaks; we'll figure out
+@c a better solution in the future
+@macro maintstart{}
+@dnindex Maintenance Concern
+@noticestart{dev}
+This system has maintenance concerns.
+@end macro
+
+@macro maintend
+@noticeend
+@end macro
+
+@macro maintenance{desc}
+@maintstart
+@footnote{\desc\}
+@maintend
+@end macro
+
+
+@c encapsulated to avoid bad TeX generation (fails compilation
+@c when inlined at call site)
+@macro maintfoot{desc}
+ @html
+
+ @end html
+@end macro
+
+
+@c non-critical maintenance notes
+@macro refactor{desc}
+@dnindex Refactor
+@devnotice{Portions of this system need refactoring.@footnote{
+ \desc\}}
+@end macro
+
+
+@c simple textual example
+@macro exnotice{text}
+@noticestart{ex}
+@strong{Example:} \text\
+@noticeend
+@end macro
+
+
+@macro tip{text}
+@noticestart{tip}
+\text\
+@noticeend
+@end macro
+
+
+@c Conveying the historical details of the project is important to
+@c understand why the system exists in the state that it does
+@c today. Use of this macro will hopefully help mitigate some of the
+@c problems noted by Peter Naur in his paper Programming as Theory Building:
+@c http://pages.cs.wisc.edu/~remzi/Naur.pdf
+@macro trivia{text}
+@noticestart{trivia}
+\text\
+@noticeend
+@end macro
+
+
+@c XML formatting
+@macro xmlnode{name}
+@samp{\name\}
+@end macro
+
+@macro xmlattr{name}
+@samp{@@\name\}
+@end macro
+
+
+@ifhtml
+@c override @math to delimit for MathJax/KaTeX/etc
+@definfoenclose math,\(,\)
+@end ifhtml
diff --git a/doc/tame.texi b/doc/tame.texi
index b4ba646b..47cd6b21 100644
--- a/doc/tame.texi
+++ b/doc/tame.texi
@@ -8,9 +8,14 @@
@c A copy of the license is included in the section entitled ``GNU Free
@c Documentation License''.
-@include version.texi
-
@c %**start of header
+@include config.texi
+@include version.texi
+@include macros.texi
+
+@c Developer Notes index (used only if DEVNOTES)
+@defindex dn
+
@setfilename tame.info
@documentencoding UTF-8
@settitle TAME Manual v@value{VERSION}
@@ -43,6 +48,12 @@ Free Documentation License".
@insertcopying
@end titlepage
+@devnotice{
+ This manual contains inline notes for developers of @tame{}.@footnote{
+ To disable for user documentation, pass @option{--disable-devnotes}
+ to @command{configure}.}
+ For an index of notes@comma{} see @ref{Developer Notes Index}.}
+
@contents
@ifnottex
@@ -56,6 +67,10 @@ Free Documentation License".
* Dependency Graph:: Dependency processing and flow analysis
* Symbol Table:: Lookup table for all objects
* License:: Document License
+* Concept Index::
+@ifset DEVNOTES
+* Developer Notes Index:: Index of pertenant notes for developers of @tame{}.
+@end ifset
@end menu
@ifnottex
@@ -63,40 +78,6 @@ Free Documentation License".
@end ifnottex
-@macro tame{}
-TAME
-@end macro
-
-@c TODO: move me
-@macro mdash{}
----
-@end macro
-
-@macro todo{str}
-@emph{[@strong{TODO: }\str\]}
-@end macro
-
-@macro ttref{ref}
-@ref{\ref\,,@code{\ref\}}
-@end macro
-
-@macro proof{str}
-@sc{Proof:} \str\ @qed
-@end macro
-
-@macro qed{}
-∎
-@end macro
-
-@macro pkgns{node}
-@code{lv:\node\}
-@end macro
-
-@ifhtml
-@c override @math to delimit for MathJax/KaTeX/etc
-@definfoenclose math,\(,\)
-@end ifhtml
-
@include about.texi
@include preproc.texi
@@ -105,4 +86,14 @@ TAME
@include license.texi
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@ifset DEVNOTES
+ @node Developer Notes Index
+ @unnumbered Developer Notes Index
+ @printindex dn
+@end ifset
+
@bye