2017-03-15 15:31:09 -04:00
|
|
|
|
@c This document is part of the Liza Data Collection Framework manual.
|
2017-06-08 14:46:51 -04:00
|
|
|
|
@c Copyright (C) 2017 R-T Specialty, LLC.
|
2017-03-15 15:31:09 -04:00
|
|
|
|
@c
|
|
|
|
|
@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
|
|
|
|
|
@c or any later version published by the Free Software Foundation;
|
|
|
|
|
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
|
|
|
@c Texts. A copy of the license is included in the section entitled ``GNU
|
|
|
|
|
@c Free Documentation License''.
|
|
|
|
|
|
2017-03-21 10:27:36 -04:00
|
|
|
|
|
|
|
|
|
@c unicode CONSTRUCTION SIGN
|
|
|
|
|
@macro constructionsign
|
|
|
|
|
🚧
|
2017-03-15 15:31:09 -04:00
|
|
|
|
@end macro
|
|
|
|
|
|
2017-03-21 10:27:36 -04:00
|
|
|
|
|
|
|
|
|
@c insert appropriate em dash for mode
|
2017-03-15 15:31:09 -04:00
|
|
|
|
@ifnottex
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@macro mdash
|
|
|
|
|
@inlinefmtifelse{html, @inlineraw{html,—}, —}
|
2017-03-15 15:31:09 -04:00
|
|
|
|
@end macro
|
|
|
|
|
@end ifnottex
|
2017-03-16 13:23:19 -04:00
|
|
|
|
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@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
|
2017-03-21 15:53:48 -04:00
|
|
|
|
@macro noticestart{type}
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@html
|
|
|
|
|
<div class="doc-notice \type\">
|
|
|
|
|
@end html
|
2017-03-21 15:53:48 -04:00
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro noticeend{}
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@html
|
|
|
|
|
</div>
|
|
|
|
|
@end html
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@c vanilla notice
|
|
|
|
|
@macro notice{text}
|
2017-03-21 15:53:48 -04:00
|
|
|
|
@noticestart{}
|
|
|
|
|
@emph{\text\}
|
|
|
|
|
@noticeend
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@c notice for developers of liza
|
|
|
|
|
@macro devnotice{text}
|
|
|
|
|
@ifset DEVNOTES
|
2018-02-02 09:37:51 -05:00
|
|
|
|
@noticestart{devnotice}
|
2017-03-21 15:53:48 -04:00
|
|
|
|
@emph{\text\}
|
|
|
|
|
@noticeend
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@end ifset
|
|
|
|
|
@end macro
|
|
|
|
|
|
2018-02-02 09:37:51 -05:00
|
|
|
|
@c implementation note for developers of liza
|
|
|
|
|
@macro devnote{text}
|
|
|
|
|
@ifset DEVNOTES
|
|
|
|
|
@noticestart{devnote}
|
|
|
|
|
\text\
|
|
|
|
|
@noticeend
|
|
|
|
|
@end ifset
|
|
|
|
|
@end macro
|
|
|
|
|
|
2017-06-21 13:20:40 -04:00
|
|
|
|
@c documentation TODO
|
|
|
|
|
@macro todo{text}
|
|
|
|
|
@devnotice{TODO: \text\}
|
|
|
|
|
@end macro
|
|
|
|
|
|
2017-03-16 13:23:19 -04:00
|
|
|
|
|
|
|
|
|
@c indicate that help is needed to produce docs
|
|
|
|
|
@macro helpwanted{}
|
|
|
|
|
@cindex TODO, Missing Docs
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@dnindex Missing Docs
|
2017-06-20 12:52:45 -04:00
|
|
|
|
@notice{There isn't much here yet. Maybe you can help?}
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@c maintenance note for developers
|
2017-03-23 09:41:41 -04:00
|
|
|
|
@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{}
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@dnindex Maintenance Concern
|
2017-03-23 09:41:41 -04:00
|
|
|
|
@noticestart{dev}
|
|
|
|
|
This system has maintenance concerns.
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro maintend
|
|
|
|
|
@noticeend
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@end macro
|
|
|
|
|
|
2017-03-23 09:41:41 -04:00
|
|
|
|
@macro maintenance{desc}
|
|
|
|
|
@maintstart
|
|
|
|
|
@footnote{\desc\}
|
|
|
|
|
@maintend
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
2017-03-21 10:27:36 -04:00
|
|
|
|
@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
|
2017-03-16 13:23:19 -04:00
|
|
|
|
@end macro
|
2017-03-21 15:57:30 -04:00
|
|
|
|
|
|
|
|
|
|
2017-03-22 12:30:00 -04:00
|
|
|
|
@c non-critical maintenance notes
|
|
|
|
|
@macro refactor{desc}
|
|
|
|
|
@dnindex Refactor
|
|
|
|
|
@devnotice{Portions of this system need refactoring.@footnote{
|
|
|
|
|
\desc\}}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
2017-03-21 15:57:30 -04:00
|
|
|
|
@c simple textual example
|
|
|
|
|
@macro exnotice{text}
|
|
|
|
|
@noticestart{ex}
|
|
|
|
|
@strong{Example:} \text\
|
|
|
|
|
@noticeend
|
|
|
|
|
@end macro
|
2017-03-21 16:36:41 -04:00
|
|
|
|
|
|
|
|
|
|
2017-03-22 14:55:06 -04:00
|
|
|
|
@macro tip{text}
|
|
|
|
|
@noticestart{tip}
|
|
|
|
|
\text\
|
|
|
|
|
@noticeend
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
2018-02-05 10:05:07 -05:00
|
|
|
|
@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
|
|
|
|
|
|
|
|
|
|
|
2017-03-21 16:36:41 -04:00
|
|
|
|
@c link to source file if URI is known, otherwise display
|
|
|
|
|
@c the path to the file
|
|
|
|
|
@ifset SRCURI
|
|
|
|
|
@macro srcref{path, display}
|
2017-06-20 12:53:14 -04:00
|
|
|
|
@url{@value{SRCURI}/\path\, @file{\display\}}
|
2017-03-21 16:36:41 -04:00
|
|
|
|
@end macro
|
2017-03-22 12:28:33 -04:00
|
|
|
|
|
|
|
|
|
@macro srcrefraw{path}
|
2017-06-20 12:53:14 -04:00
|
|
|
|
@url{@value{SRCURI}/\path\, @file{\path\}}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro srcrefjs{base,module}
|
|
|
|
|
@srcref{src/\base\/\module\.js, \module\}
|
2017-03-22 12:28:33 -04:00
|
|
|
|
@end macro
|
2018-03-07 13:39:27 -05:00
|
|
|
|
|
|
|
|
|
@macro testrefjs{base,module}
|
|
|
|
|
@srcref{test/\base\/\module\.js, \module\}
|
|
|
|
|
@end macro
|
2017-03-21 16:36:41 -04:00
|
|
|
|
@end ifset
|
|
|
|
|
|
|
|
|
|
@ifclear SRCURI
|
|
|
|
|
@macro srcref{path, display}
|
2017-03-22 12:28:33 -04:00
|
|
|
|
@srcrefraw{\path\}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro srcrefraw{path}
|
2017-03-21 16:36:41 -04:00
|
|
|
|
@file{\path\}
|
|
|
|
|
@end macro
|
2017-06-20 12:53:14 -04:00
|
|
|
|
|
|
|
|
|
@c intended to display a name without JS,
|
|
|
|
|
@c so just do that rather than the actual path
|
|
|
|
|
@macro srcrefjs{base,path}
|
2018-03-07 13:39:27 -05:00
|
|
|
|
@srcrefraw{src/\base\/\path\}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro testrefjs{base,module}
|
|
|
|
|
@srcref{test/\base\/\module\.js, \module\}
|
2017-06-20 12:53:14 -04:00
|
|
|
|
@end macro
|
2017-03-21 16:36:41 -04:00
|
|
|
|
@end ifclear
|
2017-03-22 14:55:24 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@c XML formatting
|
|
|
|
|
@macro xmlnode{name}
|
|
|
|
|
@samp{\name\}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro xmlattr{name}
|
|
|
|
|
@samp{@@\name\}
|
|
|
|
|
@end macro
|
2017-03-23 09:41:59 -04:00
|
|
|
|
|
|
|
|
|
|
2017-06-21 13:20:56 -04:00
|
|
|
|
@c JS formatting
|
|
|
|
|
@macro jsmethod{name}
|
|
|
|
|
@code{#\name\}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
|
2017-03-23 09:41:59 -04:00
|
|
|
|
@c text to avoid repeated e.g. ties and other formatting
|
|
|
|
|
@macro progxml
|
|
|
|
|
Program@tie{}XML
|
|
|
|
|
@end macro
|
2017-06-20 12:54:11 -04:00
|
|
|
|
|
|
|
|
|
@macro progxmlref
|
|
|
|
|
@ref{Program XML,,Program@tie{}XML}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro dapi
|
|
|
|
|
Data@tie{}API
|
|
|
|
|
@end macro
|
|
|
|
|
|
2017-06-28 16:12:08 -04:00
|
|
|
|
@macro dapiref
|
|
|
|
|
@dapi (@pxref{Data API,,Data@tie{}API})
|
|
|
|
|
@end macro
|
|
|
|
|
|
2017-06-20 12:54:11 -04:00
|
|
|
|
@c todo: link to reference directly
|
|
|
|
|
@macro proguicref{ref}
|
|
|
|
|
`\ref\' @proguicrefsuffix
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro proguicxref{ref}
|
|
|
|
|
See `\ref\' @proguicrefsuffix
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro proguicrefsuffix{}
|
|
|
|
|
in the Liza Program@tie{}UI Compiler manual
|
|
|
|
|
@end macro
|
2018-04-23 14:26:32 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@c common links
|
|
|
|
|
@macro mocha{}
|
|
|
|
|
@url{https://mochajs.org/,Mocha}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro chai{}
|
|
|
|
|
@url{http://www.chaijs.com/,Chai}
|
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
|
|
@macro easejs{}
|
|
|
|
|
@url{https://www.gnu.org/software/easejs,GNU ease.js}
|
|
|
|
|
@end macro
|
2018-05-04 10:50:35 -04:00
|
|
|
|
|
|
|
|
|
@macro gplvthree{}
|
|
|
|
|
@url{https://www.gnu.org/licenses/gpl.html,GNU General Public License version@tie{}3}
|
|
|
|
|
@end macro
|