summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/awesomebox
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-11-26 21:45:02 +0000
committerKarl Berry <karl@freefriends.org>2018-11-26 21:45:02 +0000
commit11ea1f565d0ede7b7fd6b1b8bddb3801beda5dce (patch)
tree1a62f5c0cbb73d8da87497245c2d94196bda7dd6 /Master/texmf-dist/doc/latex/awesomebox
parent038a07c08873a727349b98b6fc68cca3af0fad42 (diff)
awesomebox (26nov18)
git-svn-id: svn://tug.org/texlive/trunk@49256 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/awesomebox')
-rw-r--r--Master/texmf-dist/doc/latex/awesomebox/README.md31
-rw-r--r--Master/texmf-dist/doc/latex/awesomebox/awesomebox.pdfbin52064 -> 47179 bytes
-rw-r--r--Master/texmf-dist/doc/latex/awesomebox/awesomebox.tex238
3 files changed, 171 insertions, 98 deletions
diff --git a/Master/texmf-dist/doc/latex/awesomebox/README.md b/Master/texmf-dist/doc/latex/awesomebox/README.md
index c66ed3c1e28..47582479b91 100644
--- a/Master/texmf-dist/doc/latex/awesomebox/README.md
+++ b/Master/texmf-dist/doc/latex/awesomebox/README.md
@@ -1,26 +1,11 @@
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
-[FontAwesome](http://fontawesome.io/icons/) icons to ease the
-illustration of these blocks.
-
-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 requires you to use XeLaTeX too.
+aim of this package is to use [FontAwesome 5](https://fontawesome.com)
+icons to ease the illustration of these blocks.
The idea of admonition blocks comes from the ones you can easily do with
[AsciiDoc](http://asciidoctor.org/docs/user-manual/#admonition).
-We use the previous work of Honza Ustohal on
-[fontawesome.sty](https://gist.github.com/sway/3101743) to build this
-package. However, we made two important modifications:
-
-1. we rename the internal commands of `fontawesome.sty` from `\fa` to
- `\abIcon` and the `\FA` font switch to `\ABFamily` to avoid
- collision if you want to use both of them;
-2. we remove most of the provided icons to only kept the one we really
- use in this package.
-
For more details, please refer to the
[awesomebox.pdf](https://github.com/milouse/latex-awesomebox/blob/master/awesomebox.pdf)
document.
@@ -28,10 +13,12 @@ document.
Requirements
============
-- a working XeLaTeX environment
-- the `ifxetex`, `ifluatex`, `xltxtra`, `xcolor` and `tabularx` LaTeX
- packages
-- [FontAwesome](http://fontawesome.io/icons/)
+The following LaTeX packages are required (they should be already
+included in your LaTeX distribution):
+
+- `fontawesome5`
+- `xcolor`
+- `tabu`
Installation
============
@@ -40,7 +27,7 @@ Download the `awesomebox.sty` file and put it in the same folder of the
document your are composing.
For system wide installation, please refer to the documentation of your
-XeLaTeX distribution.
+LaTeX distribution.
License
=======
diff --git a/Master/texmf-dist/doc/latex/awesomebox/awesomebox.pdf b/Master/texmf-dist/doc/latex/awesomebox/awesomebox.pdf
index aa26ad521a8..1f21f7fc6e5 100644
--- a/Master/texmf-dist/doc/latex/awesomebox/awesomebox.pdf
+++ b/Master/texmf-dist/doc/latex/awesomebox/awesomebox.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/awesomebox/awesomebox.tex b/Master/texmf-dist/doc/latex/awesomebox/awesomebox.tex
index 6410cb2ace0..809c9c43694 100644
--- a/Master/texmf-dist/doc/latex/awesomebox/awesomebox.tex
+++ b/Master/texmf-dist/doc/latex/awesomebox/awesomebox.tex
@@ -3,6 +3,7 @@
\usepackage{awesomebox}
\setlength{\aweboxvskip}{0pt}
+\usepackage{xltxtra}
\defaultfontfeatures{Scale=MatchLowercase}
\setmonofont[Mapping=tex-text,Scale=0.9]{Inconsolata}
\setromanfont[Mapping=tex-text]{Linux Libertine O}
@@ -11,12 +12,15 @@
\usepackage{polyglossia}
\setdefaultlanguage{english}
+% 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[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})}
@@ -24,7 +28,7 @@
\newcommand{\colophon}{
~\vfill
\begin{center}
- \scriptsize Prepared with {\ABFamily\abIconHeart} from Nantes,
+ \scriptsize Prepared with \faHeart{} from Nantes,
France\\
Awesome Box is released under the
\hrefcolor{http://www.wtfpl.net/txt/copying/}{WTFPL}. A copy of this
@@ -47,7 +51,7 @@
\title{Awesome Boxes}
\author{Étienne Deparis}
-\date{2018-01-31 v0.2}
+\date{2018-11-26 v0.4}
\begin{document}
@@ -58,48 +62,12 @@
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
+\hrefcolor{https://fontawesome.com/}{FontAwesome 5} 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
@@ -110,6 +78,7 @@ document:
\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
@@ -126,6 +95,8 @@ The provided boxes follow the name convention of the
dictum felis. Pellentesque tortor lacus, semper et neque vitae,
egestas commodo nisl.}
+\clearpage
+
\begin{center}
\verb!\tipbox{Lorem ipsum…}!
\end{center}
@@ -137,8 +108,6 @@ The provided boxes follow the name convention of the
dictum felis. Pellentesque tortor lacus, semper et neque vitae,
egestas commodo nisl.}
-\clearpage
-
\begin{center}
\verb!\warningbox{Lorem ipsum…}!
\end{center}
@@ -172,74 +141,128 @@ The provided boxes follow the name convention of the
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} suffixe.
+
+\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:
+
+\vspace{5mm}
+
+\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}
-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.
+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
-({\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.
+(\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 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}!
+\verb!\awesomebox[rulecolor]{rulewidth}{icon}{iconcolor}{your text content}!
\end{center}
-\clearpage
+Here are some examples of custom boxes:
\begin{center}
-\verb!\awesomebox{\abIconCertificate}{5pt}{magenta}{Lorem ipsum…}!
+\verb!\awesomebox{5pt}{\faCertificate}{magenta}{Lorem ipsum…}!
\end{center}
-\awesomebox{\abIconCertificate}{5pt}{magenta}{Lorem ipsum dolor sit
- amet, consectetur adipiscing elit. Nam aliquet libero quis lectus
- elementum fermentum.
+\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.}
\begin{center}
-\verb!\awesomebox{\abIconCogs}{0pt}{black}{Lorem ipsum…}!
+\verb!\awesomebox{0pt}{\faCogs}{black}{Lorem ipsum…}!
\end{center}
-\awesomebox{\abIconCogs}{0pt}{black}{Lorem ipsum dolor sit amet,
- consectetur adipiscing elit. Nam aliquet libero quis lectus elementum
- fermentum.
+\begin{awesomeblock}{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.}
+ egestas commodo nisl.
+\end{awesomeblock}
\begin{center}
-\verb!\awesomebox{\abIconRocket}{2pt}{violet}{Lorem ipsum…}!
+\verb!\awesomebox[violet]{2pt}{\faRocket}{violet}{Lorem ipsum…}!
\end{center}
-\awesomebox{\abIconRocket}{2pt}{violet}{Lorem ipsum dolor sit
- amet, consectetur adipiscing elit. Nam aliquet libero quis lectus
- elementum fermentum.
+\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.}
+\subsection{Environments}
+
+To create your own box, with your own colour, your own icon or your own
+rule width, you can use our meta command:
+
+\begin{verbatim}
+\begin{awesomeblock}[rulecolor]{rulewidth}{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:
+
+\vspace{5mm}
+
+\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}
Finally, you can also modify some internal options in order to modify
@@ -259,7 +282,7 @@ 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:
+is -5mm and you can change it with:
\verb!\setlength{\aweboxsignraise}{-5mm}!.
\subsection{Rule width}
@@ -268,7 +291,15 @@ 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}
+\subsection{Rule default color}
+
+The 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.
@@ -280,12 +311,67 @@ Awesome boxes may be used in any other environments, like in a list.
\end{itemize}
\end{verbatim}
+will give:
+
\begin{itemize}
\item My first item
\item My second item with \notebox{A note box!}
\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:
+
+\vspace{5mm}
+
+\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}
+
+\section{Breaking changes}
+
+The version 0.4 of this package introduces 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 will now leads to compiling errors, as you must now write it
+as the following example show 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!, \verb!\warningbox!, \verb!\cautionbox!,
+and \verb!\importantbox! or the \texttt{noteblock}, \texttt{tipblock},
+\texttt{cautionblock}, \texttt{warningblock}, \texttt{importantblock}
+environment) you are not affected by this change and your documents will
+work without any change.
+
\colophon
\end{document}