1
0
Fork 0
liza/doc/macros.texi

269 lines
5.1 KiB
Plaintext
Raw Normal View History

@c This document is part of the Liza Data Collection Framework manual.
@c Copyright (C) 2017 R-T Specialty, LLC.
@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''.
@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
2017-03-16 13:23:19 -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
@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
2017-03-16 13:23:19 -04:00
@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
2017-03-16 13:23:19 -04:00
@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 link to source file if URI is known, otherwise display
@c the path to the file
@ifset SRCURI
@macro srcref{path, display}
@url{@value{SRCURI}/\path\, @file{\display\}}
@end macro
@macro srcrefraw{path}
@url{@value{SRCURI}/\path\, @file{\path\}}
@end macro
@macro srcrefjs{base,module}
@srcref{src/\base\/\module\.js, \module\}
@end macro
@macro testrefjs{base,module}
@srcref{test/\base\/\module\.js, \module\}
@end macro
@end ifset
@ifclear SRCURI
@macro srcref{path, display}
@srcrefraw{\path\}
@end macro
@macro srcrefraw{path}
@file{\path\}
@end macro
@c intended to display a name without JS,
@c so just do that rather than the actual path
@macro srcrefjs{base,path}
@srcrefraw{src/\base\/\path\}
@end macro
@macro testrefjs{base,module}
@srcref{test/\base\/\module\.js, \module\}
@end macro
@end ifclear
@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
@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
@macro progxmlref
@ref{Program XML,,Program@tie{}XML}
@end macro
@macro dapi
Data@tie{}API
@end macro
@macro dapiref
@dapi (@pxref{Data API,,Data@tie{}API})
@end macro
@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
@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
@macro gplvthree{}
@url{https://www.gnu.org/licenses/gpl.html,GNU General Public License version@tie{}3}
@end macro