path: root/fonts/asapsym/asapsym.dtx

% \iffalse meta-comment
%
% Copyright (C) 2016 by Paul D. Gessler <pdgessler@gmail.com>
% ------------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Paul D. Gessler <pdgessler@gmail.com>.
%
% This work consists of the files asapsym.dtx, asapsym.ins, and README.md;
% the compiled documentation asapsym.pdf (generated from asapsym.dtx);
% and the derived files asapsym.sty, asapsym.code.tex, and asapsym-generic.tex.
% ------------------------------------------------------------------------------
% The OpenType font file Asap-Symbol.otf is Copyright (c) 2014-2015,
% Omnibus-Type (www.omnibus-type.com <omnibus.type@gmail.com>).
% It is redistributed with this work under the terms of the SIL Open Font
% License (OFL), version 1.1. The full text of this license is available at:
%   http://scripts.sil.org/OFL_web
% ------------------------------------------------------------------------------
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{asapsym.dtx}
%</driver>
%<latexwrapper>\NeedsTeXFormat{LaTeX2e}
%<latexwrapper>\ProvidesPackage{asapsym}
%<*latexwrapper>
    [2016/03/20 v1.0 convenience macros for ASAP symbol font]
%</latexwrapper>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{asapsym,booktabs,hologo,microtype}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{asapsym.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{182}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v1.0}{2016/03/20}{Initial public release}
%
% \DoNotIndex{\@,\bgroup,\catcode,\csname,\def,\directlua,\edef,\egroup,\else,%
% \endcsname,\endinput,\errmessage,\expandafter,\fi,\ifdefined,\input,%
% \RequirePackage,\the,\XeTeXinterchartoks}
%
% \providecommand*{\url}{\texttt}
% \newcommand{\pkg}[1]{\textsf{#1}}
% \newcommand{\tr}[1]{\ttfamily\textbackslash asap#1 & \vphantom{Ag}\csname asap#1\endcsname \\}
% \newcommand{\ts}[1]{\tr{#1Sign}}
% \newcommand{\tn}[1]{\ts{Not#1}}
% \newcommand{\tp}[1]{\tr{#1}}
% \newcommand{\td}[1]{
%   \tp{Female#1}
%   \tp{Male#1}
% }
%
% \GetFileInfo{asapsym.dtx}
% \title{The \textsf{asapsym} package}
% \author{Paul D. Gessler \\ \url{pdgessler@gmail.com}}
% \date{\fileversion~from \filedate}
%
% \maketitle
%
% \section{Introduction}
%
% The \pkg{asapsym} package provides convenience macros for using the symbols
% contained in the included \emph{ASAP Symbol} font. The font is part of the
% ASAP family\footnote{\url{http://www.omnibus-type.com/fonts/asap.php}} of 
% fonts. The font is designed by Omnibus-Type\footnote{\url{http://www.omnibus-type.com/index.php}}
% and released under the SIL Open Font License (OFL)\footnote{\url{http://scripts.sil.org/OFL}},
% version 1.1.
%
% Development of the package is currently hosted on GitHub\footnote{\url{http://github.com/pdgessler/asapsym}}. 
% You are welcome to follow development, submit any issues you discover, or
% suggest improvements/enhancements using the web interface there.
%
% \section{Usage}
%
% To use the macros, you must use an OTF-capable engine with \hologo{eTeX}
% extensions (\hologo{XeTeX} or \hologo{LuaTeX} both fit the bill). To load the
% macros, choose the loading mechanism based on the format you are using:
% \begin{verbatim}
%  \usepackage{asapsym}    % LaTeX
%  \input asapsym.code.tex % Plain TeX\end{verbatim}
%
% Once the package is loaded, all macros are available for use throughout your
% document. Refer to sections \ref{sec:arrows} to \ref{sec:transportation} for
% a complete listing of macros and their resulting symbols, grouped by category.
%
% \section{Future Work}
%
% In future releases, I plan to add:
% \begin{itemize}
% \item color support for the `not' sign overlays,
% \item switches/options for displaying male/female variants of the people 
%   symbols, 
% \item alias commands for custom user naming, and
% \item \hologo{ConTeXt} support.
% \end{itemize}
%
% \section{Arrows} \label{sec:arrows}
% \begin{tabular}{lc}
% \toprule
% Macro & Symbol \\
% \midrule
% \tr{ArrowLeft}
% \tr{ArrowUpLeft}
% \tr{ArrowUp}
% \tr{ArrowUpRight}
% \tr{ArrowRight}
% \tr{ArrowDownRight}
% \tr{ArrowDown}
% \tr{ArrowDownLeft}
% \tr{ArrowCircleOpenLeft}
% \tr{ArrowCircleOpenUpLeft}
% \tr{ArrowCircleOpenUp}
% \tr{ArrowCircleOpenUpRight}
% \tr{ArrowCircleOpenRight}
% \tr{ArrowCircleOpenDownRight}
% \tr{ArrowCircleOpenDown}
% \tr{ArrowCircleOpenDownLeft}
% \tr{ArrowCircleFillLeft}
% \tr{ArrowCircleFillUpLeft}
% \tr{ArrowCircleFillUp}
% \tr{ArrowCircleFillUpRight}
% \tr{ArrowCircleFillRight}
% \tr{ArrowCircleFillDownRight}
% \tr{ArrowCircleFillDown}
% \tr{ArrowCircleFillDownLeft}
% \bottomrule
% \end{tabular}
% 
% \section{Elevators}
% \begin{tabular}{lc}
% \toprule
% Macro & Symbol \\
% \midrule
% \tr{Elevator}
% \tr{Stair}
% \tr{StairDown}
% \tr{StairUp}
% \tr{Escalator}
% \tr{EscalatorDown}
% \tr{EscalatorUp}
% \bottomrule
% \end{tabular}
% 
% \section{Objects}
% \begin{tabular}{lc}
% \toprule
% Macro & Symbol \\
% \midrule
% \tr{Book}
% \tr{Envelope}
% \tr{Gift}
% \tr{Locker}
% \tr{LostAndFound}
% \tr{Microscope}
% \tr{Cross}
% \tr{Phone}
% \tr{MobilePhone}
% \tr{Tablet}
% \tr{Monitor}
% \tr{Utensils}
% \tr{Mug}
% \tr{Hanger}
% \tr{Cigarette}
% \bottomrule
% \end{tabular}
% 
% \section{People}
% \begin{tabular}{lc}
% \toprule
% Macro & Symbol \\
% \midrule
% \td{WithServiceAnimal}
% \td{WalkingDog}
% \td{Walking}
% \td{WithLuggageWaving}
% \td{WithLuggageWaiting}
% \td{DiscardingTrash}
% \td{AtHelpDesk}
% \td{HoldingInfant}
% \td{WalkingStroller}
% \td{WithChild}
% \tp{WalkingCane}
% \tp{WaitingSeated}
% \td{AtDrinkingFountain}
% \td{Adult}
% \td{Child}
% \tp{WheelchairStationary}
% \tp{WheelchairInMotion}
% \tp{Pregnant}
% \tp{GroupMeeting}
% \tp{Cycling}
% \tp{Dog}
% \tp{Infant}
% \bottomrule
% \end{tabular}
% 
% \section{Signals}
% \begin{tabular}{lc}
% \toprule
% Macro & Symbol \\
% \midrule
% \ts{Information}
% \ts{Hospital}
% \ts{Help}
% \ts{Dollar}
% \ts{Emergency}
% \ts{Parking}
% \ts{Walk}
% \ts{Dog}
% \ts{MobilePhone}
% \ts{Cigarette}
% \ts{Not}
% \midrule
% \tn{Information}
% \tn{Hospital}
% \tn{Help}
% \tn{Dollar}
% \tn{Emergency}
% \tn{Parking}
% \tn{Walk}
% \tn{Dog}
% \tn{MobilePhone}
% \tn{Cigarette}
% \bottomrule
% \end{tabular}
% 
% \section{Transportation} \label{sec:transportation}
% \begin{tabular}{lc}
% \toprule
% Macro & Symbol \\
% \midrule
% \tr{Boat}
% \tr{Helicopter}
% \tr{AirplaneOverhead}
% \tr{AirplaneTakeoff}
% \tr{AirplaneLanding}
% \tr{Bicycle}
% \tr{Automobile}
% \tr{Taxi}
% \tr{AutomobileWithKey}
% \tr{Bus}
% \tr{Train}
% \bottomrule
% \end{tabular}
%
% \StopEventually{}
%
% \section{Implementation}
%
% The implementation of the macros is divided into three parts:
% \begin{itemize}
% \item a \LaTeX\ package wrapper file (|asapsym.sty|),
% \item a Plain \TeX\ loader file (|asapsym.code.tex|), and
% \item the generic macro definition file (|asapsym-generic.tex|).
% \end{itemize}
% The third file is read in by each of the first two files after their own
% format-specific macros are defined.
%
% \subsection{\LaTeX\ Package Wrapper}
% \iffalse
%<*latexwrapper>
% \fi
%
% We use \pkg{fontspec} for loading OTF fonts and create a new font family to be
% used by the package:
%    \begin{macrocode}
\RequirePackage{fontspec}
\newfontfamily{\asapsym}{Asap Symbol}
%    \end{macrocode}
% The \pkg{fontspec} package takes care of requiring OTF-capable engines,
% producing a prominent error if one is not being used.
%
% \begin{macro}{\asapsym@raw}
% The |\asapsym@raw|\marg{stylistic-set}\marg{character} macro is used
% internally to typeset the actual symbol. The first argument is the stylistic
% set from which the symbol is to be taken. For simplicity, the leading zero
% must be present for stylistic sets 9 and below. The second argument is the
% character where symbol exists in the chosen stylistic set.
%    \begin{macrocode}
\def\asapsym@raw#1#2{\bgroup\asapsym%
  \addfontfeatures{StylisticSet=#1}#2\egroup}
%    \end{macrocode}
% The font is selected, the stylistic set applied, and the character is typeset
% within a group.
% \end{macro}
%
% Having defined the only format-specific code, the generic code is |\input|:
%    \begin{macrocode}
\input{asapsym-generic}
%    \end{macrocode}
%
% \iffalse
%</latexwrapper>
% \fi
%
% \subsection{Plain \TeX\ Loader}
% \iffalse
%<*plainwrapper>
% \fi
%
% We adopt the \LaTeX\ convention of using |@| in protected macro names
% throughout the code. Therefore, we must first save the current category code
% of |@| for later restoration, and set its category code to `letter`
%    \begin{macrocode}
\edef\asapsymatcode{\the\catcode`\@}
\catcode`\@=11
%    \end{macrocode}
%
% Next, we do some engine detection to ensure that a compatible one is used:
%    \begin{macrocode}
\ifdefined\XeTeXinterchartoks % we are in XeTeX
\else\ifdefined\directlua     % we are in LuaTex
%    \end{macrocode}
% For \hologo{LuaTeX}, we use |luaotfload.sty| so that the same font loading
% syntax may be used in \hologo{XeTeX} and \hologo{LuaTeX}:
%    \begin{macrocode}
    \input luaotfload.sty
%    \end{macrocode}
% If a compatible engine is not detected, we issue an error message and stop
% loading the remainder of the file:
%    \begin{macrocode}
  \else  % not supported
    \errmessage{asapsym error: Not an OTF-capable engine! Use xetex or luatex}
    \expandafter\endinput
  \fi
\fi
%    \end{macrocode}
%
% \begin{macro}{\asapsym@raw}
% The |\asapsym@raw|\marg{stylistic-set}\marg{character} macro is used
% internally to typeset the actual symbol, similar to the \LaTeX\ variant.
% Here, we use the |\font| primitive to select the font and stylistic set:
%    \begin{macrocode}
\def\asapsym@raw#1#2{\bgroup\font\asapsym =
  "[Asap-Symbol.otf]:+ss#1"\asapsym #2\egroup}
%    \end{macrocode}
% \end{macro}
%
% Having defined all the format-specific code, the generic code is |\input|:
%    \begin{macrocode}
\input asapsym-generic
%    \end{macrocode}
%
% Finally, we restore the category code of |@|:
%    \begin{macrocode}
\catcode`\@=\asapsymatcode
%    \end{macrocode}
%
% \iffalse
%</plainwrapper>
% \fi
%
% \subsection{Generic Macro Code}
% \iffalse
%<*generic>
% \fi
%
% Define a prefix to be used by all user-facing macros:
%    \begin{macrocode}
\def\asapsym@prefix{asap}
%    \end{macrocode}
%
% \begin{macro}{\asapsym@set}
% The |\asapsym@set|\marg{type}\marg{stylistic-set} macro defines a helper macro
% for a given `type' of symbol.
%    \begin{macrocode}
\def\asapsym@set#1#2{\expandafter\def%
  \csname\asapsym@prefix #1\endcsname##1{\asapsym@raw{#2}{##1}}}
%    \end{macrocode}
% \end{macro}
%
% Define a helper macro for each `type' of symbol. The font is implemented such
% that each `type' of symbol exists within a specific stylistic set:
%    \begin{macrocode}
\asapsym@set{arrow}{06}
\asapsym@set{elevator}{03}
\asapsym@set{object}{04}
\asapsym@set{people}{01}
\asapsym@set{signal}{05}
\asapsym@set{transport}{02}
%    \end{macrocode}
%
% \begin{macro}{\asapsym@sym}
% The |\asapsym@sym|\marg{base-name}\marg{type}\marg{char} defines a
% user-facing symbol macro. The resulting macro's |\csname| is comprised of
% the package prefix and \marg{base-name}. The symbol is taken from character
% slot \marg{char} of the stylistic set corresponding to \marg{type}.
%    \begin{macrocode}
\def\asapsym@sym#1#2#3{\expandafter\def%
  \csname\asapsym@prefix#1\endcsname{\csname\asapsym@prefix#2\endcsname{#3}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{asapsym@mka}
% |\asapsym@mka|\marg{base-name}\marg{char} is used to create a user-facing
% arrow symbol macro. The macro name is comprised of the package prefix, a
% prefix |Arrow|, and \marg{base-name}. The symbol is taken from character slot
% \marg{char} of the arrows font.
%    \begin{macrocode}
\def\asapsym@mka#1#2{\asapsym@sym{Arrow#1}{arrow}{#2}}
%    \end{macrocode}
% \end{macro}
%
% All arrows are defined using the \emph{make arrow} helper macro:
%    \begin{macrocode}
\asapsym@mka{Left}{A}
\asapsym@mka{UpLeft}{B}
\asapsym@mka{Up}{C}
\asapsym@mka{UpRight}{D}
\asapsym@mka{Right}{E}
\asapsym@mka{DownRight}{F}
\asapsym@mka{Down}{G}
\asapsym@mka{DownLeft}{H}
\asapsym@mka{CircleOpenLeft}{I}
\asapsym@mka{CircleOpenUpLeft}{J}
\asapsym@mka{CircleOpenUp}{K}
\asapsym@mka{CircleOpenUpRight}{L}
\asapsym@mka{CircleOpenRight}{M}
\asapsym@mka{CircleOpenDownRight}{N}
\asapsym@mka{CircleOpenDown}{O}
\asapsym@mka{CircleOpenDownLeft}{P}
\asapsym@mka{CircleFillLeft}{Q}
\asapsym@mka{CircleFillUpLeft}{R}
\asapsym@mka{CircleFillUp}{S}
\asapsym@mka{CircleFillUpRight}{T}
\asapsym@mka{CircleFillRight}{U}
\asapsym@mka{CircleFillDownRight}{V}
\asapsym@mka{CircleFillDown}{W}
\asapsym@mka{CircleFillDownLeft}{X}
%    \end{macrocode}
%
% \begin{macro}{asapsym@mke}
% |\asapsym@mke|\marg{base-name}\marg{char} is used to create a user-facing
% elevator symbol macro. The macro name is comprised of the package prefix and
% \marg{base-name}. The symbol is taken from character slot \marg{char} of the
% elevators font.
%    \begin{macrocode}
\def\asapsym@mke#1#2{\asapsym@sym{#1}{elevator}{#2}}
%    \end{macrocode}
% \end{macro}
%
% All elevators are defined using the \emph{make elevator} helper macro:
%    \begin{macrocode}
\asapsym@mke{Elevator}{A}
\asapsym@mke{Stair}{B}
\asapsym@mke{StairDown}{C}
\asapsym@mke{StairUp}{D}
\asapsym@mke{Escalator}{E}
\asapsym@mke{EscalatorDown}{F}
\asapsym@mke{EscalatorUp}{G}
%    \end{macrocode}
%
% \begin{macro}{asapsym@mko}
% |\asapsym@mko|\marg{base-name}\marg{char} is used to create a user-facing
% object symbol macro. The macro name is comprised of the package prefix and
% \marg{base-name}. The symbol is taken from character slot \marg{char} of the
% objects font.
%    \begin{macrocode}
\def\asapsym@mko#1#2{\asapsym@sym{#1}{object}{#2}}
%    \end{macrocode}
% \end{macro}
%
% All objects are defined using the \emph{make object} helper macro:
%    \begin{macrocode}
\asapsym@mko{Book}{A}
\asapsym@mko{Envelope}{B}
\asapsym@mko{Gift}{C}
\asapsym@mko{Locker}{D}
\asapsym@mko{LostAndFound}{E}
\asapsym@mko{Microscope}{F}
\asapsym@mko{Cross}{G}
\asapsym@mko{Phone}{H}
\asapsym@mko{MobilePhone}{I}
\asapsym@mko{Tablet}{J}
\asapsym@mko{Monitor}{K}
\asapsym@mko{Utensils}{L}
\asapsym@mko{Mug}{M}
\asapsym@mko{Hanger}{N}
\asapsym@mko{Cigarette}{O}
%    \end{macrocode}
%
% \begin{macro}{asapsym@mkp}
% |\asapsym@mkp|\marg{base-name}\marg{char} is used to create a user-facing
% people symbol macro. The macro name is comprised of the package prefix and
% \marg{base-name}. The symbol is taken from character slot \marg{char} of the
% people font.
%    \begin{macrocode}
\def\asapsym@mkp#1#2{\asapsym@sym{#1}{people}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{asapsym@mkd}
% |\asapsym@mkd|\marg{base-name}\marg{char} is used to create gender-specific
% user-facing people symbol macros. The macro names are comprised of the package
% prefix, |Male| or |Female| as the case may be, and \marg{base-name}. The
% symbols are taken from character slot \marg{char} of the people font.
%    \begin{macrocode}
\def\asapsym@mkd#1#2{
  \asapsym@mkp{Male#1}{\uppercase{#2}}
  \asapsym@mkp{Female#1}{\lowercase{#2}}}
%    \end{macrocode}
% \end{macro}
%
% All people are defined using the \emph{make people} helper macro. Some
% symbols have the gender-specific variants, while others do not. |\asapsym@mkd|
% and |\asapsym@mkp| are used as appropriate.
%    \begin{macrocode}
\asapsym@mkd{WithServiceAnimal}{A}
\asapsym@mkd{WalkingDog}{B}
\asapsym@mkd{Walking}{C}
\asapsym@mkd{WithLuggageWaving}{D}
\asapsym@mkd{WithLuggageWaiting}{E}
\asapsym@mkd{DiscardingTrash}{F}
\asapsym@mkd{AtHelpDesk}{G}
\asapsym@mkd{HoldingInfant}{H}
\asapsym@mkd{WalkingStroller}{I}
\asapsym@mkd{WithChild}{J}
\asapsym@mkp{WalkingCane}{K}
\asapsym@mkp{WaitingSeated}{L}
\asapsym@mkd{AtDrinkingFountain}{M} % ??? is this correct ???
\asapsym@mkd{Adult}{N}
\asapsym@mkd{Child}{O}
\asapsym@mkp{WheelchairStationary}{P}
\asapsym@mkp{WheelchairInMotion}{p}
\asapsym@mkp{Pregnant}{Q}
\asapsym@mkp{GroupMeeting}{R}
\asapsym@mkp{Cycling}{S}
\asapsym@mkp{Dog}{T}
\asapsym@mkp{Infant}{U}
%    \end{macrocode}
%
% \begin{macro}{asapsym@mks}
% |\asapsym@mks|\marg{base-name}\marg{char} is used to create user-facing sign
% symbol macros, along with `negated' versions. The macro names are comprised
% of the package prefix, |Not| for negated versions, \marg{base-name}, and
% |Sign|. The symbols are taken from character slot \marg{char} of the people
% font. For the negated versions, the not sign is overlaid.
%    \begin{macrocode}
\def\asapsym@mks#1#2{
  \asapsym@sym{#1Sign}{signal}{#2}
  \asapsym@sym{Not#1Sign}{signal}{#2\llap{X}}}
%    \end{macrocode}
% \end{macro}
%
% All signals are defined using the \emph{make signal} helper macro:
%    \begin{macrocode}
\asapsym@mks{Information}{A}
\asapsym@mks{Hospital}{B}
\asapsym@mks{Help}{C}
\asapsym@mks{Dollar}{D}
\asapsym@mks{Emergency}{E}
\asapsym@mks{Parking}{F}
\asapsym@mks{Walk}{G}
\asapsym@mks{Dog}{H}
\asapsym@mks{MobilePhone}{I}
\asapsym@mks{Cigarette}{J}
\asapsym@mks{Not}{X}
%    \end{macrocode}
%
% \begin{macro}{asapsym@mkt}
% |\asapsym@mkt|\marg{base-name}\marg{char} is used to create a user-facing
% transporation symbol macro. The macro name is comprised of the package prefix and
% \marg{base-name}. The symbol is taken from character slot \marg{char} of the
% transportation font.
%    \begin{macrocode}
\def\asapsym@mkt#1#2{\asapsym@sym{#1}{transport}{#2}}
%    \end{macrocode}
% \end{macro}
%
% All transports are defined using the \emph{make transportation} helper macro:
%    \begin{macrocode}
\asapsym@mkt{Boat}{A}
\asapsym@mkt{Helicopter}{B}
\asapsym@mkt{AirplaneOverhead}{C}
\asapsym@mkt{AirplaneTakeoff}{D}
\asapsym@mkt{AirplaneLanding}{E}
\asapsym@mkt{Bicycle}{F}
\asapsym@mkt{Automobile}{G}
\asapsym@mkt{Taxi}{H}
\asapsym@mkt{AutomobileWithKey}{I}
\asapsym@mkt{Bus}{J}
\asapsym@mkt{Train}{K}
%    \end{macrocode}
%
% \iffalse
%</generic>
% \fi
%
% \Finale
\endinput