1
0
Fork 0
liza/doc/macros.texi

243 lines
4.6 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters!

This file contains invisible Unicode characters that may be processed differently from what appears below. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to reveal hidden characters.

@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
@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 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
@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{\base\/\path\}
@end macro
@end ifclear
@c XML formatting
@macro xmlnode{name}
@samp{\name\}
@end macro
@macro xmlattr{name}
@samp{@@\name\}
@end macro
@c JS formatting
@macro jsmethod{name}
@code{#\name\}
@end macro
@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