From 1b4ebc13e39cf9fcf05d567ac81bf8b84f3730f1 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 10:27:36 -0400 Subject: [PATCH] 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 | 2 +- configure.ac | 13 ++++++- doc/.gitignore | 1 + doc/Makefile.am | 3 +- doc/config.texi.in | 4 +++ doc/liza.css | 34 +++++++++++++++++++ doc/liza.texi | 22 +++++++++++- doc/macros.texi | 84 +++++++++++++++++++++++++++++++++++++++++----- 8 files changed, 149 insertions(+), 14 deletions(-) create mode 100644 doc/config.texi.in diff --git a/.gitignore b/.gitignore index 6f4a0e4..7634d5d 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,7 @@ Makefile.in # generated by configure src/version.js -config.* +/config.* Makefile package.json diff --git a/configure.ac b/configure.ac index de67f47..1f13a55 100644 --- a/configure.ac +++ b/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 diff --git a/doc/.gitignore b/doc/.gitignore index 8e3f7df..6eab057 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -19,3 +19,4 @@ Makefile Makefile.in stamp-vti version.texi +config.texi diff --git a/doc/Makefile.am b/doc/Makefile.am index 8dab2e6..b992de5 100644 --- a/doc/Makefile.am +++ b/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 diff --git a/doc/config.texi.in b/doc/config.texi.in new file mode 100644 index 0000000..314c443 --- /dev/null +++ b/doc/config.texi.in @@ -0,0 +1,4 @@ +@c Manual configuration + +@c whether to include notes for Liza developers +@SET_DEVNOTES@ diff --git a/doc/liza.css b/doc/liza.css index 4f53562..1142098 100644 --- a/doc/liza.css +++ b/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; +} diff --git a/doc/liza.texi b/doc/liza.texi index 220112e..bce42b7 100644 --- a/doc/liza.texi +++ b/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 diff --git a/doc/macros.texi b/doc/macros.texi index a9dd018..f656e4a 100644 --- a/doc/macros.texi +++ b/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 +
+@end html +@emph{\text\} +@html +
+@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 +
+ @end html + \desc\ + + @emph{Developers should evaluate whether extra time should be + allocated for tasks involving this system.} + @html +
+ @end html @end macro