diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/awesomebox/awesomebox.tex |
Initial commit
Diffstat (limited to 'graphics/awesomebox/awesomebox.tex')
-rw-r--r-- | graphics/awesomebox/awesomebox.tex | 477 |
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} |