%%
%% This is file `ascii-emoticon-user-guide.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% ascii-emoticon-code.dtx  (with options: `user')
%% 
%% This file is from version 1.0 of the free and open-source
%% LaTeX package "ascii-emoticon," released August 2026.
%% 
%% Copyright 2026 Conrad Kosowsky
%% 
%% This file may be distributed and modified under the terms
%% of the LaTeX Public Project License, version 1.3c or any
%% later version. The most recent version of this license is
%% available online at
%% 
%%           https://www.latex-project.org/lppl/
%% 
%% This work has the LPPL status "maintained," and the current
%% maintainer is the package author, Conrad Kosowsky. He can
%% be reached at kosowsky.latex@gmail.com.
%% 
%% PLEASE KNOW THAT THIS FREE SOFTWARE IS PROVIDED WITHOUT
%% ANY WARRANTY. SPECIFICALLY, THE "NO WARRANTY" SECTION OF
%% THE LATEX PROJECT PUBLIC LICENSE STATES THE FOLLOWING:
%% 
%% THERE IS NO WARRANTY FOR THE WORK. EXCEPT WHEN OTHERWISE
%% STATED IN WRITING, THE COPYRIGHT HOLDER PROVIDES THE WORK
%% `AS IS’, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
%% OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
%% WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
%% PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
%% OF THE WORK IS WITH YOU. SHOULD THE WORK PROVE DEFECTIVE,
%% YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR
%% CORRECTION.
%% 
%% IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED
%% TO IN WRITING WILL THE COPYRIGHT HOLDER, OR ANY AUTHOR
%% NAMED IN THE COMPONENTS OF THE WORK, OR ANY OTHER PARTY
%% WHO MAY DISTRIBUTE AND/OR MODIFY THE WORK AS PERMITTED
%% ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
%% SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT
%% OF ANY USE OF THE WORK OR OUT OF INABILITY TO USE THE WORK
%% (INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA, DATA BEING
%% RENDERED INACCURATE, OR LOSSES SUSTAINED BY ANYONE AS A
%% RESULT OF ANY FAILURE OF THE WORK TO OPERATE WITH ANY
%% OTHER PROGRAMS), EVEN IF THE COPYRIGHT HOLDER OR SAID
%% AUTHOR OR SAID OTHER PARTY HAS BEEN ADVISED OF THE
%% POSSIBILITY OF SUCH DAMAGES.
%% 
%% For more information, see the LaTeX Project Public License.
%% Derivative works based on this software may come with their
%% own license or terms of use, and the package author is not
%% responsible for any third-party software.
%% 
%% Happy TeXing!
%% 
\makeatletter
\documentclass[12pt]{article}
\usepackage[margin=1in]{geometry}
\usepackage[factor=700,stretch=14,shrink=14,step=1]{microtype}
\usepackage{booktabs}
\usepackage{tabularx}
\usepackage{shortvrb}

\MakeShortVerb{|}
\edef\pipe{\string|}
\let\sectionname\relax

\tabcolsep=3pt

\def\meta#1{$\langle$\textit{#1}$\rangle$}

\newbox\mybox
\setbox\mybox\hbox{\ttfamily--------}
\def\colwd{\wd\mybox}

\begin{document}

\def\documentname{User Guide}
\input ascii-emoticon-heading.tex

\noindent The \textsf{ascii-emoticon} package defines control sequences for 222 ASCII emoticons. This package does not provide access to emojis---other packages can accomplish that task. The package provides two modest advantages over typing emoticons by hand. First, control sequences can shorten the names of long emoticons. For example, |\fish| is easier to type than |><))v)'>|. Second, \textsf{ascii-emoticon} handles catcodes automatically, which saves the user from having to type |\verb| or use unexpandable control sequence such as |\$| or |\%|, which can be relevant for certain niche use cases. I divided the control sequences into ``standard'' emoticons, which I've seen before or found references to, and ``nonstandard'' emoticons, which are short strings that vaguely resemble their meaning. Emoticons work in regular text and math mode.

Users who want to create their own emoticons or redefine the commands in this package should use |\DeclareEmoticon|. It should appear only in the preamble, and its syntax is
\begin{code}
|\DeclareEmoticon{|\meta{control sequence}|}{|\meta{emoticon}|}|
\end{code}
This command defines \textit{control sequence} to expand to \textit{emoticon}. The emoticon can contain any special characters other than |\|, |{|, and |}|. To include these characters in the \textit{emoticon}, users should type |\\|, |\{|, or |\}| respectively. The package will not redefine control sequences that already have meanings if those meanings are not emoticons. If you must redefine a control sequence, say |\mycs|, to be an emoticon, you should undefine it by typing
\begin{code}
|\let\mycs\undefined|
\end{code}
before using |\DeclareEmoticon|.

Control sequence names are straightforward. A |p| at the beginning of the control sequence means parentheses, and an |n| at the end means ``nose'' (in the case of face-like emoticons). Each emoticon control sequence typesets the characters normally, and you can add |tt| to the beginning of the control sequence to convert the characters to the current fixed-width font. For example, |\smiley| produces :), and |\ttsmiley| produces |:)|.

For advanced users: emoticon control sequences are not expandable, but if you need the list of characters that form the emoticon, for example to include inside an |\edef| or |\write|, you should preface the emoticon name with |\emoticon|. For example,
\begin{code}
|\immediate\write\mywrite{\winkyn}|
\end{code}
writes |\winkyn| to |\mywrite|, but
\begin{code}
|\immediate\write\mywrite{\emoticon\winkyn}|
\end{code}
writes |;-)| to |\mywrite|. If you use |\emoticon| with a |tt| emoticon name, you will end up with an extra |\ttfamily|. The |\emoticon| command is not valid in math mode.

\begin{figure}[t]
\centerline{\bfseries Standard Emoticons\strut}
\noindent\begin{tabularx}\textwidth{p{\colwd}Xp{\colwd}Xp{\colwd}X}\toprule
Mark & Control Sequence & Mark & Control Sequence & Mark & Control Sequence\\\midrule
|$_$| & |\payday| & |*<]:)| & |\santa| & |>:)| & |\evil| \\
\texttt{\@percentchar)} & |\confused| & |*<]:-)| & |\santan| & |>:-(| & |\madn| \\
\texttt{\@percentchar-)} & |\confusedn| & |*_*| & |\crazy| & |>:-)| & |\eviln| \\
\texttt{\@percentchar\string_\@percentchar} & |\steampunk| & |--_--| & |\soporific| & |>;)| & |\devious| \\
|'-'| & |\unphased| & |-_-| & |\derp| & |>;-)| & |\deviousn| \\
|($_$)| & |\ppayday| & |._.| & |\awake| & |><))v)'>| & |\fish| \\
\texttt{(\@percentchar\string_\@percentchar)} & |\psteampunk| & |:'(| & |\cry| & |>_<| & |\ugh| \\
|('-')| & |\punphased| & |:'-(| & |\cryn| & |?_?| & |\questioning| \\
|('-')>| & |\salute| & |:(| & |\sad| & |@>-->--| & |\rose| \\
|(*^.^*)| & |\lovely| & \texttt{:(\pipe)} & |\monkey| & |@_@| & |\amazed| \\
|(*_*)| & |\pcrazy| & |:)| & |\smiley| & \texttt{@\@charrb->->-} & |\varrose| \\
|(--_--)| & |\psoporific| & |:-(| & |\sadn| & |[-o-]| & |\vartiefighter| \\
|(-_-)| & |\pderp| & \texttt{:-(\pipe)} & |\monkeyn| & |[:]| & |\robot| \\
|(._.)| & |\pawake| & |:-)| & |\smileyn| & \texttt{\@backslashchar(\string^o\string^)/} & |\woot| \\
|(._.)?| & |\calling| & |:-/| & |\mehn| & |^_^| & |\happy| \\
|(::[]::)| & |\bandage| & |:-3| & |\catn| & |^_^'| & |\unsure| \\
|(;_;)| & |\ptears| & |:-D| & |\grinn| & |B)| & |\sunglasses| \\
|(=^.^=)~| & |\fatcat| & |:-P| & |\tonguen| & |B-)| & |\sunglassesn| \\
|(=_=)| & |\psleepy| & |:-X| & |\keepsecretn| & |i_i| & |\eyebags| \\
|(=_=)zzz| & |\asleep| & |:/| & |\meh| & |m('u')m| & |\varkilroy| \\
|(>._.)>| & |\hug| & |:3| & |\cat| & |m(._.)m| & |\kilroy| \\
|(>_<)| & |\pugh| & |:D| & |\grin| & |n(.m.)n| & |\bat| \\
|(?_?)| & |\pquestioning| & |:P| & |\tongue| & |O:)| & |\angel| \\
|(@_@)| & |\pamazed| & |:X| & |\keepsecret| & |O:-)| & |\angeln| \\
|(^_^')| & |\punsure| & |;)| & |\winky| & |o_o| & |\hello| \\
|(^_^)| & |\phappy| & |;-)| & |\winkyn| & |o_O| & |\uhoh| \\
|(_)3| & |\beercup| & |;-D| & |\jokeyn| & |o_q| & |\monocle| \\
|(_)>| & |\teacup| & |;_;| & |\tears| & \texttt{o\@charlb-<]} & |\skateboard| \\
|(i_i)| & |\peyebags| & |;D| & |\jokey| & |p_q| & |\glasses| \\
|(o_o)| & |\phello| & |<('O')>| & |\wow| & |T_T| & |\teyes| \\
|(o_O)| & |\puhoh| & |<(^o^)>| & |\amazing| & |V.v.V| & |\crab| \\
|(o_q)| & |\pmonocle| & |<(`^`)>| & |\gah| & |X-D| & |\laughingn| \\
|(p_q)| & |\pglasses| & |</3| & |\broken| & |x_x| & |\dead| \\
|(T_T)| & |\pteyes| & |<3| & |\heart| & |XD| & |\laughing| \\
|(x_x)| & |\pdead| & |<:3(_)~~| & |\mouse| & \texttt{\pipe-o-\pipe} & |\tiefighter| \\
|(~_~)| & |\pworried| & |=_=| & |\sleepy| & \texttt{\string~(\_:-(\pipe)} & |\homer| \\
|****:-)| & |\marge| & |>:(| & |\mad| & |~_~| & |\worried| \\
\bottomrule
\end{tabularx}
\end{figure}

\begin{figure}[t]
\centerline{\bfseries Nonstandard Emoticons\strut}
\noindent\begin{tabularx}\textwidth{p{\colwd}Xp{\colwd}Xp{\colwd}X}\toprule
Mark & Control Sequence & Mark & Control Sequence & Mark & Control Sequence\\\midrule
|!_!| & |\rabbit| & |<"=| & |\duckling| & |[&]| & |\office| \\
|#| & |\tictactoe| & |<*>| & |\sunburst| & |[+]| & |\moth| \\
\texttt{\@percentchar>-} & |\varbouquet| & |<+>| & |\batling| & |[?]| & |\powerup| \\
|(!)| & |\bang| & |<@>| & |\penguin| & |[]| & |\sandwich| \\
|(&)| & |\shrine| & |<]| & |\paperhat| & |^*^| & |\bee| \\
|(*)| & |\pufferfish| & |<^>| & |\goose| & |^?^| & |\coatl| \\
|(?)| & |\riddle| & |<O>| & |\evileye| & |^@^| & |\dragon| \\
|(@)| & |\mollusk| & \texttt{<\pipe:} & |\witch| & |c-| & |\mushroom| \\
|(O)| & |\eyeball| & \texttt{<\pipe>} & |\stingray| & |C>-| & |\pear| \\
|*| & |\star| & |=+=| & |\satellite| & |D-| & |\bell| \\
|*-*| & |\barbell| & |=-*| & |\comet| & |D--| & |\plunger| \\
|*8:| & |\troll| & |=D~| & |\plug| & |D>-| & |\sconce| \\
|*:>| & |\rooster| & |>| & |\gnat| & |E3| & |\bread| \\
|*~*| & |\bola| & |>"<| & |\crabling| & |E3~| & |\toast| \\
|+-3| & |\anchor| & |>*<| & |\bonbon| & |o+<| & |\human| \\
|-| & |\twig| & \texttt{>-\@charlb} & |\chalice| & |X*~| & |\campfire| \\
|-(| & |\wine| & |>.<| & |\mole| & \texttt{\@charlb*\@charrb} & |\dragonfruit| \\
|-*| & |\flower| & |>>| & |\gnu| & \texttt{\pipe:\pipe} & |\street| \\
|-*D| & |\horseshoecrab| & |>>>| & |\python| & \texttt{\pipe=\pipe} & |\bridge| \\
|--| & |\stick| & |>j<| & |\dragonfly| & \texttt{\@charrb-3} & |\chandelier| \\
|--E| & |\trident| & |@| & |\snail| & |~| & |\worm| \\
|-;| & |\hammer| & |@-*| & |\potato| & |~*| & |\polyp| \\
|-<| & |\antibody| & |@-3| & |\nettle| & |~*:| & |\mouseling| \\
|-<>| & |\cottoncandy| & |@->| & |\weevil| & |~*>| & |\rat| \\
|-<D| & |\luminaire| & |@.?| & |\lion| & |~*X| & |\alligator| \\
|-=| & |\knife| & |@:| & |\frog| & |~:>| & |\fox| \\
|-E| & |\fork| & |@:-| & |\squid| & |~=| & |\candle| \\
|-O| & |\spoon| & |@:>| & |\peacock| & |~=*| & |\dog| \\
|-o| & |\lollipop| & |@=C| & |\phage| & |~=>| & |\wolf| \\
\texttt{-\@charlb} & |\martini| & |@>-| & |\bouquet| & |~=[| & |\gulper| \\
|.^.| & |\rocket| & |@@| & |\owl| & |~=I| & |\hammerhead| \\
|:-| & |\mosquito| & |@@:| & |\caterpillar| & |~^>| & |\shark| \\
|:-:| & |\branch| & |@@@| & |\eggs| & |~D| & |\tea| \\
|:=:| & |\logs| & |@^>| & |\lizard| & |~o| & |\tadpole| \\
|:>| & |\bird| & |@~| & |\jellyfish| & |~~| & |\snake| \\
|:@:| & |\beetle| & |@~<| & |\fishbones| & |~~<| & |\viper| \\
|:O:| & |\bug| & |@~>| & |\demon| & |~~D| & |\soup| \\
\bottomrule
\end{tabularx}
\end{figure}

\end{document}
\endinput
%%
%% End of file `ascii-emoticon-user-guide.tex'.
