Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMike Gerwitz <mike.gerwitz@rtspecialty.com>2019-01-29 16:09:00 -0500
committerMike Gerwitz <mike.gerwitz@rtspecialty.com>2019-01-30 13:44:24 -0500
commit290cf1b6e68bd357bc2d867f34496b37ed8ce9aa (patch)
tree6e70084e9fa9d94fdd1f980ae1fefdbb2cecb0ad
parent7f6961272cddcaac02a1de6c8faed161987c93d3 (diff)
downloadtame-290cf1b6e68bd357bc2d867f34496b37ed8ce9aa.tar.gz
tame-290cf1b6e68bd357bc2d867f34496b37ed8ce9aa.tar.bz2
tame-290cf1b6e68bd357bc2d867f34496b37ed8ce9aa.zip
doc: Copied developer-related macros from Liza
This includes, notably, the Developer Notes feature. I did not copy any SRCUI stuff since this project uses literate documentation, but I'll add it if it seems like it will be useful. Barely any of the project is written literately right now. * .gitignore: `{=>/}config.*'. * configure.ac (SET_DEVNOTES): New variable. (AC_CONFIG_FILES): Add `doc/config.texi'. * doc/.gitignore (config.texi): Ignore (generated). * doc/Makefile.am (tame_TEXINFOS): Add `macros.texi' and `config.texi'. * doc/config.texi.in: New file. * doc/macros.texi: New file containing some macros from `doc/tame.texi' and some from Liza's `doc/macros.texi'. * doc/tame.texi: Adjust position of header comment. Include `config.texi' and `macros.texi'. Add devnotice to header. Strip out macros. (menu): Add `Concept Index' and conditional `Developer Notes Index'. (Concept Index, Developer Notes Index): New nodes (latter conditional).
-rw-r--r--.gitignore2
-rw-r--r--configure.ac12
-rw-r--r--doc/.gitignore3
-rw-r--r--doc/Makefile.am3
-rw-r--r--doc/config.texi.in4
-rw-r--r--doc/macros.texi197
-rw-r--r--doc/tame.texi61
7 files changed, 244 insertions, 38 deletions
diff --git a/.gitignore b/.gitignore
index f085b66..847752f 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 59ad044..a4551fa 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 14d345e..cc458a8 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 93125f2..bdd3ce7 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 0000000..f628528
--- /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 0000000..436d692
--- /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,&mdash;}, —}
+@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
+<div class="doc-notice \type\">
+@end html
+@end macro
+
+@macro noticeend{}
+@html
+</div>
+@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
+ <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
+
+
+@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 b4ba646..47cd6b2 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''.
+@c %**start of header
+@include config.texi
@include version.texi
+@include macros.texi
+
+@c Developer Notes index (used only if DEVNOTES)
+@defindex dn
-@c %**start of header
@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