summaryrefslogtreecommitdiff
path: root/graphics/awesomebox/awesomebox.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/awesomebox/awesomebox.tex
Initial commit
Diffstat (limited to 'graphics/awesomebox/awesomebox.tex')
-rw-r--r--graphics/awesomebox/awesomebox.tex477
1 files changed, 477 insertions, 0 deletions
diff --git a/graphics/awesomebox/awesomebox.tex b/graphics/awesomebox/awesomebox.tex
new file mode 100644
index 0000000000..7794b80459
--- /dev/null
+++ b/graphics/awesomebox/awesomebox.tex
@@ -0,0 +1,477 @@
+\documentclass[a4paper,12pt]{article}
+
+\usepackage{awesomebox}
+
+\usepackage{xltxtra}
+\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{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{http://asciidoctor.org/docs/user-manual/\#admonition}{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{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.}
+
+\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 overriden 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 overriden 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{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}