Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'doc/macros.texi')
-rw-r--r--doc/macros.texi197
1 files changed, 197 insertions, 0 deletions
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,—}, —}
+@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