tame/doc/macros.texi

@c  This document is part of the TAME manual.
@c  Copyright (C) 2014-2023 Ryan 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}
@dnindex TODO
@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