awesomebox.tex

\documentclass[a4paper,12pt]{article}

\usepackage{awesomebox}

\usepackage{xltxtra}
\defaultfontfeatures{Scale=MatchLowercase}
\setmonofont[
  Path = fonts/,
  Extension = .otf,
  Mapping = tex-text,
  Scale = 0.9]{Inconsolata}
\setromanfont[
  Path = fonts/,
  Extension = .otf,
  BoldFont = *B,
  ItalicFont = *I,
  BoldItalicFont = *BI,
  Mapping = tex-text]{LinLibertine_R}
\setsansfont[
  Path=fonts/,
  Extension = .otf,
  BoldFont = *B,
  ItalicFont = *I,
  Mapping = tex-text]{LinBiolinum_R}

\usepackage{polyglossia}
\setdefaultlanguage{english}

\usepackage{minted}

% Comment out the lines above and uncomment the following lines to test
% usage with pdflatex
%\usepackage[utf8]{inputenc}
%\usepackage[T1]{fontenc}
%\usepackage[english,frenchb]{babel}

\usepackage{geometry}
\geometry{
  xetex,
  vmargin=2cm,
  hmargin=3cm,
  includeheadfoot,
  nomarginpar
}
\linespread{1.2}

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

\usepackage{datetime}
\newcommand{\colophon}{
  ~\vfill
  \begin{center}
    \scriptsize Handcrafted with \faHeart{} 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}
}

\title{Awesome Boxes}
\author{Étienne Deparis}
\date{2019-07-27 v0.6}

% 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}}}

\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{https://fontawesome.com/}{FontAwesome 5} icons to ease the
illustration of these boxes.

The idea of admonition blocks comes from the ones you can easily do with
\hrefcolor{https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/}{AsciiDoc}.

\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}
\subsection{Inline boxes}

The provided boxes follow the name convention of the
\hrefcolor{http://asciidoctor.org/docs/user-manual/\#admonition}{admonition
  blocks} from \hrefcolor{https://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.}

\clearpage

\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.}

\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.}

\subsection{Environments}
\label{sec:environments}

You can also insert admonition blocks with an environment syntax. The
same names can be used, but with a \emph{block} suffix.

\begin{verbatim}
\begin{noteblock}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
aliquet libero quis lectus elementum fermentum.
\end{noteblock}
\end{verbatim}

For the exactly same rendering:

\begin{noteblock}
  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.
\end{noteblock}

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

This package use the
\hrefcolor{https://www.ctan.org/pkg/fontawesome5}{FontAwesome5 package}
under the hood. In order to use your own icons, just call the proper
\verb!\faXxx! command.

For example, if you want to add the \emph{rocket} icon
(\faRocket), you just have to  insert \verb!\faRocket!.

\section{How to create your own box?}
\label{sec:howtoown}
\subsection{Inline boxes}

To create your own box, with your own icon and colour, your own
vertical rule width and colour, your own horizontal rules at the top
and the bottom of your boxes, or a title, you can use our meta
command:

\begin{center}
\verb!\awesomebox[vrulecolor][hrule][title]{vrulewidth}{icon}{iconcolor}{content}!
\end{center}

Here are some examples of custom boxes:

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

\awesomebox{5pt}{\faCertificate}{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.}

\clearpage

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

\awesomebox{0pt}{\faCogs}{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[violet]{2pt}{\faRocket}{violet}{Lorem ipsum…}!
\end{center}

\awesomebox[violet]{2pt}{\faRocket}{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.}

\vspace{2mm}
\begin{center}
\small\verb!\awesomebox[white][\abShortLine]{0pt}{\faGrinBeam[regular]}{black}{Lorem ipsum…}!
\end{center}

\awesomebox[white][\abShortLine]{0pt}{\faGrinBeam[regular]}{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.}

\vspace{2mm}
\begin{center}
\small\verb!\awesomebox[white][\abLongLine][\textbf{Watch out}]{0pt}{\faBomb}{black}{Lorem…}!
\end{center}

\awesomebox[white][\abLongLine][\textbf{Watch out}]{0pt}{\faBomb}{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.}

\subsection{Environments}

To create your own box, with your own icon and colour, your own
vertical rule width and colour, your own horizontal rules at the top
and the bottom of your boxes, or a title, you can use our meta
command:

\begin{verbatim}
\begin{awesomeblock}[vrulecolor][hrule][title]{vrulewidth}{icon}{iconcolor}
  your text content
\end{awesomeblock}
\end{verbatim}

For example, we can rewrite the first previous example as:

\begin{verbatim}
\begin{awesomeblock}[magenta]{5pt}{\faCertificate}{magenta}
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam aliquet
  libero quis lectus elementum fermentum.
\end{awesomeblock}
\end{verbatim}

Which will render this way:

\begin{awesomeblock}[magenta]{5pt}{\faCertificate}{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.
\end{awesomeblock}


\section{Other options}

Some internal options can be customized, in order to globally modify
your awesome boxes (either the default ones or your new ones).

\subsection{Left margin}

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

You must declare you new length \emph{after} the \verb!\begin{document}!
instruction, or your custom length will be overridden by the default
one.

\subsection{Content width}

The content width is the space used to insert the body of your
admonition block. You can change it with the following command
(\verb!0.88\linewidth! is the default one):\\
\verb!\setlength{\aweboxcontentwidth}{0.88\linewidth}!.

You must declare you new length \emph{after} the \verb!\begin{document}!
instruction, or your custom length will be overridden by the default
one.

\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}!.

You can put your new length either in the header or in the body of your
document.

\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}!.

You can put your new length either in the header or in the body of your
document.

\subsection{Vertical 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}!.

You can put your new length either in the header or in the body of your
document.

\subsection{Vertical rule default color}

The vertical rule color is an optional argument passed to the commands
or environments. Its default value is the following (to match the one
defined by AsciiDoctor) and you can change it this way:
\verb!\definecolor{abvrulecolor}{RGB}{221,221,216}!.

\section{In the wild}

\subsection{Compatibility with inline commands}

Awesome boxes are drawn with the help of a \texttt{tabular}
environment. All the glitches that you may encounter with tables will
happen with awesomebox too. Good news is, the respective solution work
too.

For example, footnotes are known to behave badly with tables: the
upraised number will appear, but the footnote definition will never be
appended at the end of the page. To fix that, either for tables or for
awesomeboxes, you should follow
\hrefcolor{https://tex.stackexchange.com/questions/109467/footnote-in-tabular-environment}{this
  answer on StackOverflow} and use the \texttt{footnote} package
alongside the command \texttt{\textbackslash
  make\-save\-note\-env\{tabular\}}.

\begin{verbatim}
  \documentclass{article}
  \usepackage{footnote}
  \makesavenoteenv{tabular}
  \begin{document}
  \begin{noteblock}
    Content\footnote{footnote text}
  \end{noteblock}
  \end{document}
\end{verbatim}

\subsection{Compatibility with other environments}

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

\begin{verbatim}
\begin{itemize}
\item My first item
\item Lorem ipsum… \notebox{Fusce aliquet…}
\item Last and finally
\end{itemize}
\end{verbatim}

will give:

\begin{itemize}
\item My first item
\item Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam
  aliquet libero quis lectus elementum fermentum. \notebox{Fusce aliquet
    augue sapien, non efficitur mi ornare sed. Morbi at dictum
    felis. Pellentesque tortor lacus, semper et neque vitae, egestas
    commodo nisl.}
\item Last and finally
\end{itemize}

It may contain other environments too, but in that case, you should
prefer the environment API (see Section \ref{sec:environments}):

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

will give:

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

Or with a more complex example with minted environment:

\begin{verbatim}
\begin{noteblock}
  This could be written as:

  \begin{minted}{c++}
    std::cout << "hello world!" << std::endl;
  \end{minted}
\end{noteblock}
\end{verbatim}

\begin{noteblock}
  This could be written as:

  \begin{minted}{c++}
    std::cout << "hello world!" << std::endl;
  \end{minted}
\end{noteblock}

\section{Breaking changes}

\subsection{Version 0.6}

This version improved a lot block components rendering. Historically,
awesome box used fixed length to display icon and content. This leads to
admonition block to overflow or to be thinner than paragraphs around.

Please note that we change default block components width in purpose. It
used to be \verb!0.08\linewidth! for the margin and
\verb!0.92\linewidth! for the content. It is now \verb!0.12\linewidth!
for the margin and \verb!0.88\linewidth! for the content.

We now compute the default \verb!\aweboxleftmargin! and
\verb!\aweboxcontentwidth! value in a \verb!\AtBeginDocument!
command. Thus, to avoid your custom lengths to be overriden by the
default ones, you must declare them \emph{after} the
\verb!\begin{document}! instruction.

\subsection{Version 0.4}

This version introduced a way to customize the rule color. Thus, the
commands and environments arguments have been reorganized to be in a
more logical order.

Historically, the \verb!\awesomebox! command used the following syntax:

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

This syntax now leads to compiling errors, as you must now write it
as the following example shows you (and as explained in the section
\ref{sec:howtoown} "\nameref{sec:howtoown}"), to avoid an alternate
declaration of rule and icon options:

\begin{center}
\verb!\awesomebox[rulecolor]{rulewidth}{icon}{iconcolor}{your text content}!
\end{center}

If you only use the provided boxes and environments (the
\verb!\notebox!, \verb!\tipbox!, \texttt{\textbackslash warn\-ing\-box},
\verb!\cautionbox!, \verb!\importantbox! commands or the
\texttt{noteblock}, \texttt{tipblock}, \texttt{caution\-block},
\texttt{warningblock}, \texttt{importantblock} environments) you are not
affected by this change and your documents will work without any change.

\colophon

\end{document}