Add notices and DEVNOTES flag

* .gitignore (/config.*): Restrict to root.
* configure.ac (DEVNOTES): Add variable.
  (--enable-devnotes): Add configuration flag.
* doc/Makefile.am (liza_TEXINFOS): config.texi dependency.
* doc/config.texi.in: Add configuration file.
* doc/liza.css: Styling for notices.
* doc/liza.texi: Include configuration.  Add notice for DEVNOTES.
* doc/macros.texi: Add notice macros.
* doc/.gitignore (config.texi): Ignore generated file.

.gitignore

@@ -7,7 +7,7 @@ Makefile.in
 
 # generated by configure
 src/version.js
-config.*
+/config.*
 Makefile
 package.json
 

configure.ac

@@ -41,6 +41,17 @@ AS_IF([node --harmony_destructuring >/dev/null 2>/dev/null],
        AC_SUBST([NODE_DESTRUCTURE], [--harmony_destructuring])],
       [AC_MSG_RESULT(no)])
 
+set_devnotes='@set DEVNOTES'
+AC_ARG_ENABLE(
+  [devnotes],
+  [AS_HELP_STRING([--enable-devnotes],
+                  [include note for liza developers (enabled by default)])],
+  [test "x$enableval" != xno || set_devnotes="@c $set_devnotes"])
+
+AC_SUBST([SET_DEVNOTES], [$set_devnotes])
+
 # generate files from their *.in counterparts
-AC_CONFIG_FILES([Makefile doc/Makefile package.json src/version.js])
+AC_CONFIG_FILES([Makefile package.json
+                 doc/Makefile doc/config.texi
+                 src/version.js])
 AC_OUTPUT

doc/.gitignore

@@ -19,3 +19,4 @@ Makefile
 Makefile.in
 stamp-vti
 version.texi
+config.texi

doc/Makefile.am

@@ -21,5 +21,4 @@
 MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css
 
 info_TEXINFOS = liza.texi
-liza_TEXINFOS = design.texi macros.texi
-
+liza_TEXINFOS = design.texi macros.texi config.texi

doc/config.texi.in

@@ -0,0 +1,4 @@
+@c Manual configuration
+
+@c whether to include notes for Liza developers
+@SET_DEVNOTES@

doc/liza.css

@@ -1,5 +1,6 @@
 /*
 Copyright (C) 2016-2017 Oliver Heimlich
+Copyright (C) 2017 LoVullo Associates, Inc.
 
 This file is part of Octave.
 
@@ -110,3 +111,36 @@ but don't sacrifice space on small screens.
     body { margin-left: 7.5em; }
   }
 }
+
+/** added by LoVullo Associates **/
+.doc-notice
+{
+    border-left: 5px solid #657b83;
+    margin:  0px;
+    padding: 0em 0em 0em 0.25em;
+    padding-block-start: 0.25em;
+    padding-block-end: 0.25em;
+}
+
+.doc-notice p
+{
+    margin: 0px;
+}
+
+.doc-notice.dev
+{
+    border-color: #d33682;
+}
+
+.doc-notice.dev p::before
+{
+    color: #d33682;
+    content: '\01F6A7';
+    margin-right: 0.5em;
+}
+
+.footnote-notice.dev p:first-child::before
+{
+    content: '\01F6A7';
+    margin-right: 0.5em;
+}

doc/liza.texi

@@ -10,7 +10,12 @@
 @c    Free Documentation License''.
 
 @c %**start of header
+@include config.texi
 @include version.texi
+@include macros.texi
+
+@c Developer Notes index (used only if DEVNOTES)
+@defindex dn
 
 @setfilename liza.info
 @settitle Liza Data Collection Framework v@value{VERSION}
@@ -47,6 +52,12 @@ Free Documentation License''.
 @insertcopying
 @end titlepage
 
+@devnotice{
+  This manual contains inline notes for developers of Liza.@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
@@ -57,6 +68,9 @@ Free Documentation License''.
 @menu
 * Design and Architecture:Design.  Design and structure of framework
 * Concept Index::
+@ifset DEVNOTES
+* Developer Notes Index::  Index of pertenant notes for developers of Liza.
+@end ifset
 @end menu
 
 @ifnottex
@@ -64,11 +78,17 @@ Free Documentation License''.
 @insertcopying
 @end ifnottex
 
-@include macros.texi
 @include design.texi
 
 @node Concept Index
 @unnumbered Concept Index
 @printindex cp
 
+@ifset DEVNOTES
+  @node Developer Notes Index
+  @unnumbered Developer Notes Index
+  @printindex dn
+@end ifset
+
+
 @bye

doc/macros.texi

@@ -8,22 +8,88 @@
 @c    Texts.  A copy of the license is included in the section entitled ``GNU
 @c    Free Documentation License''.
 
-@c insert appropriate em dash for mode
-@iftex
-@macro mdash{}
----
-@end macro
-@end iftex
 
+@c unicode CONSTRUCTION SIGN
+@macro constructionsign
+🚧
+@end macro
+
+
+@c insert appropriate em dash for mode
 @ifnottex
-@macro mdash{}
-—
+@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 rawnotice{type,text}
+@html
+<div class="doc-notice \type\">
+@end html
+@emph{\text\}
+@html
+</div>
+@end html
+@end macro
+
+
+@c vanilla notice
+@macro notice{text}
+@rawnotice{{},\text\}
+@end macro
+
+
+@c notice for developers of liza
+@macro devnotice{text}
+@ifset DEVNOTES
+@html
+@end html
+@rawnotice{dev,\text\}
+@end ifset
+@end macro
+
 
 @c indicate that help is needed to produce docs
 @macro helpwanted{}
 @cindex TODO, Missing Docs
-@emph{There's nothing here yet.  Maybe you can help?}
+@dnindex Missing Docs
+@notice{There's nothing here yet.  Maybe you can help?}
+@end macro
+
+
+@c maintenance note for developers
+@macro maintenance{desc}
+@dnindex Maintenance Concern
+@devnotice{This system has maintenance concerns.@footnote{
+  @maintfoot{\desc\}
+}}
+@end macro
+
+@c encapsulated to avoid bad TeX generation (fails compilation
+@c when inlined at call site)
+@macro maintfoot{desc}
+  @html
+  <div class="footnote-notice dev">
+  @end html
+  \desc\
+
+  @emph{Developers should evaluate whether extra time should be
+          allocated for tasks involving this system.}
+  @html
+  </div>
+  @end html
 @end macro