\documentclass[a4paper,12pt]{article}

\usepackage{awesomebox}
\setlength{\aweboxvskip}{0pt}

\defaultfontfeatures{Scale=MatchLowercase}
\setmonofont[Mapping=tex-text,Scale=0.9]{Inconsolata}
\setromanfont[Mapping=tex-text]{Linux Libertine O}
\setsansfont[Mapping=tex-text]{Linux Biolinum O}

\usepackage{polyglossia}
\setdefaultlanguage{english}

\usepackage[vmargin=2cm,hmargin=3cm,includeheadfoot=true]{geometry}
\linespread{1.2}

\def\abIconRocket{\symbol{"F135}}
\def\abIconHeart{\symbol{"F004}}

\newcommand{\cf}[1]{(\emph{cf.} section \ref{#1}, %
  <<\,\nameref{#1}\,>>, p. \pageref{#1})}

\usepackage{datetime}
\newcommand{\colophon}{
  ~\vfill
  \begin{center}
    \scriptsize Prepared with {\ABFamily\abIconHeart} from Nantes,
    France\\
    Awesome Box is released under the
    \hrefcolor{http://www.wtfpl.net/txt/copying/}{WTFPL}. A copy of this
    license is distributed in this package.\\
    \tiny version of the \today{} --- \currenttime
  \end{center}
}

% configuration de la transformation en PDF
\usepackage[pdfusetitle]{hyperref}
\hypersetup{
  colorlinks=false,
  pdfborder=0 0 0,
  breaklinks=true,
  bookmarksopen=true,
  pdfcreator=XeLaTeX,
  pdfproducer=XeLaTeX}

\newcommand\hrefcolor[2]{\textcolor{magenta}{\href{#1}{#2}}}

\title{Awesome Boxes}
\author{Étienne Deparis}
\date{2018-01-31 v0.2}

\begin{document}

\maketitle

\section{Introduction}

Awesome Boxes is all about drawing admonition blocks around text to
inform or alert your readers about something particular. The specific
aim of this package is to use
\hrefcolor{http://fontawesome.io/icons/}{FontAwesome} icons to ease the
illustration of these boxes.

This means all the magic of this package only exists if you previously
installed FontAwesome on your system and made it available for use with
\XeTeX. Yes, this package require you to use \XeLaTeX\ too.

The idea of admonition blocks comes from the ones you can easily do with
\hrefcolor{http://asciidoctor.org/docs/user-manual/\#admonition}{AsciiDoc}.

We use the previous work of Honza Ustohal on
\hrefcolor{https://gist.github.com/sway/3101743}{fontawesome.sty} to
build this package. However, we made two important modifications:

\begin{enumerate}
\item we rename the internal commands of \texttt{fontawesome.sty} from
  \texttt{\textbackslash{}fa} to \texttt{\textbackslash{}abIcon} and the
  \texttt{\textbackslash{}FA} font switch to
  \texttt{\textbackslash{}ABFamily} to avoid collision if you want to
  use both of them;
\item we remove most of the provided icons to only kept the one we
  really use in this package. We'll see later how to add back some of
  them \cf{sec:new-icons}.
\end{enumerate}

Therefore, the only symbols we kept are the following:

\begin{description}
  \item[{\ABFamily\abIconCheck}] \verb!\ABFamily\abIconCheck!
  \item[{\ABFamily\abIconInfoCircle}] \verb!\ABFamily\abIconInfoCircle!
  \item[{\ABFamily\abIconFire}] \verb!\ABFamily\abIconFire!
  \item[{\ABFamily\abIconExclamationCircle}] \verb!\ABFamily\abIconExclamationCircle!
  \item[{\ABFamily\abIconExclamationTriangle}] \verb!\ABFamily\abIconTriangle!
  \item[{\ABFamily\abIconCogs}] \verb!\ABFamily\abIconCogs!
  \item[{\ABFamily\abIconThumbsUp}] \verb!\ABFamily\abIconThumbsUp!
  \item[{\ABFamily\abIconThumbsDown}] \verb!\ABFamily\abIconThumbsDown!
  \item[{\ABFamily\abIconCertificate}] \verb!\ABFamily\abIconCertificate!
  \item[{\ABFamily\abIconLightBulb}] \verb!\ABFamily\abIconLightBulb!
  \item[{\ABFamily\abIconTwitter}] \verb!\ABFamily\abIconTwitter!
  \item[{\ABFamily\abIconGithub}] \verb!\ABFamily\abIconGithub!
\end{description}

\section{How to use it?}

Just download this package and call it at the beginning of your
document:

\begin{center}
\verb!\usepackage{awesomebox}!
\end{center}

\section{Provided boxes}

The provided boxes follow the name convention of the
\hrefcolor{http://asciidoctor.org/docs/user-manual/\#admonition}{admonition
  blocks} from \hrefcolor{http://asciidoctor.org}{AsciiDoc}.

\begin{center}
\verb!\notebox{Lorem ipsum…}!
\end{center}

\notebox{Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
  aliquet libero quis lectus elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\begin{center}
\verb!\tipbox{Lorem ipsum…}!
\end{center}

\tipbox{Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
  aliquet libero quis lectus elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\clearpage

\begin{center}
\verb!\warningbox{Lorem ipsum…}!
\end{center}

\warningbox{Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
  aliquet libero quis lectus elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\begin{center}
\verb!\cautionbox{Lorem ipsum…}!
\end{center}

\cautionbox{Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
  aliquet libero quis lectus elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\begin{center}
\verb!\importantbox{Lorem ipsum…}!
\end{center}

\importantbox{Lorem ipsum dolor sit amet, consectetur adipiscing
  elit. Nam aliquet libero quis lectus elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\section{How to add new icons?}
\label{sec:new-icons}

If you look at the \texttt{awesomebox.sty} source code, you'll see that
the current icons are declared using the following command:
\verb!\def\abIconFire{\symbol{"F06D}}!.

As you can see, adding a new icon is as simple as creating a new
\verb!\def! command with the right hexadecimal code. These codes can be
found on the \hrefcolor{http://fontawesome.io/cheatsheet/}{FontAwesome
  cheatsheet}. All you have to do is to convert the provided html-entity
to the \TeX\ compatible code.

For example, if you want to add the \emph{rocket} icon
({\ABFamily\abIconRocket}), you have to translate \verb![&#xf135;]! to
\texttt{"F135}. And that's it:
\verb!\def\abIconRocket{\symbol{"F135}}!.

You can put this new \verb!\def! command at the beginning of your
document, just before the \verb!\begin{document}! for exemple.

\section{How to create your own box?}

To create your own box, with your own colour, your own icon or your own
rule width, you can use our meta command:

\begin{center}
\verb!\awesomebox{icon}{rulewidth}{color}{your text content}!
\end{center}

\clearpage

\begin{center}
\verb!\awesomebox{\abIconCertificate}{5pt}{magenta}{Lorem ipsum…}!
\end{center}

\awesomebox{\abIconCertificate}{5pt}{magenta}{Lorem ipsum dolor sit
  amet, consectetur adipiscing elit. Nam aliquet libero quis lectus
  elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\begin{center}
\verb!\awesomebox{\abIconCogs}{0pt}{black}{Lorem ipsum…}!
\end{center}

\awesomebox{\abIconCogs}{0pt}{black}{Lorem ipsum dolor sit amet,
  consectetur adipiscing elit. Nam aliquet libero quis lectus elementum
  fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\begin{center}
\verb!\awesomebox{\abIconRocket}{2pt}{violet}{Lorem ipsum…}!
\end{center}

\awesomebox{\abIconRocket}{2pt}{violet}{Lorem ipsum dolor sit
  amet, consectetur adipiscing elit. Nam aliquet libero quis lectus
  elementum fermentum.

  Fusce aliquet augue sapien, non efficitur mi ornare sed. Morbi at
  dictum felis. Pellentesque tortor lacus, semper et neque vitae,
  egestas commodo nisl.}

\section{Other options}

Finally, you can also modify some internal options in order to modify
globally your awesome boxes (either the default ones or your new ones).

\subsection{Left margin}

The left margin is the space left before the vertical rule to display
the icon. You can change it with the following command (9mm is the
default one): \\ \verb!\setlength{\aweboxleftmargin}{9mm}!.

\subsection{Vertical skip}

This space is used before and after the awesome box. You can change it
with (5mm is the default): \verb!\setlength{\aweboxvskip}{5mm}!.

\subsection{Sign raise}

This length is used to raise (or lower) the left icon. Its default value
is −5mm and you can change it with:
\verb!\setlength{\aweboxsignraise}{-5mm}!.

\subsection{Rule width}

This width is used for the vertical rule of our four default boxes. Its
default value is 2pt and you can change it with:
\verb!\setlength{\aweboxrulewidth}{2pt}!.

\section{In other environments}

Awesome boxes may be used in any other environments, like in a list.

\begin{verbatim}
\begin{itemize}
\item My first item
\item My second item with \notebox{A note box!}
\item Last and finally
\end{itemize}
\end{verbatim}

\begin{itemize}
\item My first item
\item My second item with \notebox{A note box!}
\item Last and finally
\end{itemize}

\colophon

\end{document}
