summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/easyformat
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 /macros/latex/contrib/easyformat
Initial commit
Diffstat (limited to 'macros/latex/contrib/easyformat')
-rw-r--r--macros/latex/contrib/easyformat/README18
-rw-r--r--macros/latex/contrib/easyformat/easyformat.pdfbin0 -> 47183 bytes
-rw-r--r--macros/latex/contrib/easyformat/easyformat.sty186
-rw-r--r--macros/latex/contrib/easyformat/easyformat.tex290
4 files changed, 494 insertions, 0 deletions
diff --git a/macros/latex/contrib/easyformat/README b/macros/latex/contrib/easyformat/README
new file mode 100644
index 0000000000..bc6d0d3921
--- /dev/null
+++ b/macros/latex/contrib/easyformat/README
@@ -0,0 +1,18 @@
+easyformat is a package that allows the use of _ (the underscore)
+to add italics and bold text and ^ (the circumflex) to add smallcaps.
+
+Usage:
+Import the package with: \usepackage{easyformat}
+
+Now you can do the following in textmode:
+_italics_, __bold__, ___bolditalic___ and ^smallcaps^.
+
+The underscore's (_) and circumflex's (^) meaning in
+mathmode stay the same.
+
+(See easyformat.pdf for more info.)
+
+
+A package by Evert Provoost, licensed under GPLv3.
+
+Made with <3 in Berlaar, Belgium.
diff --git a/macros/latex/contrib/easyformat/easyformat.pdf b/macros/latex/contrib/easyformat/easyformat.pdf
new file mode 100644
index 0000000000..35c2a89dac
--- /dev/null
+++ b/macros/latex/contrib/easyformat/easyformat.pdf
Binary files differ
diff --git a/macros/latex/contrib/easyformat/easyformat.sty b/macros/latex/contrib/easyformat/easyformat.sty
new file mode 100644
index 0000000000..9b8bc4424d
--- /dev/null
+++ b/macros/latex/contrib/easyformat/easyformat.sty
@@ -0,0 +1,186 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% %
+% easyformat Easily add boldface, italics and smallcaps in LaTeX. %
+% Copyright (C) 2017 Evert Provoost <evert.provoost@gmail.com> %
+% %
+% This program is free software: you can redistribute it and/or modify %
+% it under the terms of the GNU General Public License as published by %
+% the Free Software Foundation, either version 3 of the License, or %
+% (at your option) any later version. %
+% %
+% This program is distributed in the hope that it will be useful, %
+% but WITHOUT ANY WARRANTY; without even the implied warranty of %
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the %
+% GNU General Public License for more details. %
+% %
+% You should have received a copy of the GNU General Public License %
+% along with this program. If not, see <http://www.gnu.org/licenses/>. %
+% %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%% NOTE TO THE FUTURE:
+% In LaTeX3 the `New Font Selection Scheme' is replaced
+% by XFSS (xfont). Moving will require some research.
+
+
+%% Administration...
+\RequirePackage{expl3}[2016/04/21]
+\ProvidesExplPackage
+ {easyformat}
+ {2017/06/03}
+ {1.4.0}
+ {Easily add boldface, italics and smallcaps.}
+
+
+%% Public macros
+% Add macros to switch the syntax on or off.
+\cs_new:Npn \enableeasyformat
+ {
+ \char_set_catcode_active:N _
+ \char_set_catcode_active:N ^
+ }
+
+\cs_new:Npn \disableeasyformat
+ {
+ \char_set_catcode_math_subscript:N _
+ \char_set_catcode_math_superscript:N ^
+ }
+
+% Add a macro LaTeX should have...
+% Which is protected to fix the double superscript error
+% and able to give correct kerning in mathmode.
+\cs_new_protected:Npn \cir
+ {
+ \mode_if_math:TF
+ { \hat{} }
+ { \c_circumflex_str }
+ }
+
+
+%% Variables
+% Remember the style before changing to italics/boldface/smallcaps.
+\str_new:N \l__prev_shape_str
+\str_set_eq:NN \l__prev_shape_str \shapedefault
+
+\str_new:N \l__prev_case_str
+% Case is the option used in XFSS, however do note that in
+% LaTeX2e's NFSS, smallcaps is a kind of shape.
+\str_set_eq:NN \l__prev_case_str \shapedefault
+
+\str_new:N \l__prev_series_str
+\str_set_eq:NN \l__prev_series_str \seriesdefault
+
+
+%% Formating handling
+% Add macros which change the font shape and font series.
+\cs_new:Npn \__font_set_shape:n #1
+ {
+ \fontshape {#1}
+ \selectfont
+ }
+
+\cs_new:Npn \__font_set_series:n #1
+ {
+ \fontseries {#1}
+ \selectfont
+ }
+
+% Switch italics on or off.
+\cs_new:Npn \__handle_italics:
+ {
+ \str_if_eq:NNTF \f@shape \itdefault
+ {
+ \__font_set_shape:n {\l__prev_shape_str}
+ \str_set_eq:NN \l__prev_shape_str \shapedefault
+ % \maybe@ic adds italics correction if needed.
+ % Probably becomes \xfss_maybe_ic: in LaTeX3.
+ \maybe@ic
+ }
+ {
+ \str_set_eq:NN \l__prev_shape_str \f@shape
+ \itshape
+ }
+ }
+
+% Switch smallcaps on or off.
+\cs_new:Npn \__handle_smallcaps:
+ {
+ \str_if_eq:NNTF \f@shape \scdefault
+ {
+ \__font_set_shape:n {\l__prev_case_str}
+ \str_set_eq:NN \l__prev_case_str \shapedefault
+ }
+ {
+ \str_set_eq:NN \l__prev_case_str \f@shape
+ \scshape
+ }
+ }
+
+% Switch boldface on or off.
+\cs_new:Npn \__handle_boldface:
+ {
+ \str_if_eq:NNTF \f@series \bfdefault
+ {
+ \__font_set_series:n {\l__prev_series_str}
+ \str_set_eq:NN \l__prev_series_str \seriesdefault
+ }
+ {
+ \str_set_eq:NN \l__prev_series_str \f@series
+ \bfseries
+ }
+ }
+
+
+%% Handling the syntax
+% This is where the magic happens (also differentiates between
+% text- and mathmode.)
+% These are protected because they should also work in eg. \section{}
+
+% Syntax handling for the underscore: italics and boldface.
+\cs_new_protected:Npn \__syntax_underscore:
+ {
+ \mode_if_math:TF
+ { \c_math_subscript_token }
+ {
+ \peek_charcode_remove:NTF _
+ % The second underscore is removed when detected.
+ { \__handle_boldface: }
+ { \__handle_italics: }
+ }
+ }
+
+% Syntax handling for the circumflex: smallcaps.
+\cs_new_protected:Npn \__syntax_circumflex:
+ {
+ \mode_if_math:TF
+ { \c_math_superscript_token }
+ { \__handle_smallcaps: }
+ }
+
+% Now give the underscore and the circumflex their behaviour.
+\char_set_active_eq:NN _ \__syntax_underscore:
+\char_set_active_eq:NN ^ \__syntax_circumflex:
+
+
+%% Activate the systems.
+% First disable the Expl3 syntax as it will only cause trouble.
+\ExplSyntaxOff
+
+% Now enable the easyformat syntax.
+\enableeasyformat
+
+% DONE!!!
+
+
+%% IMPLEMENTATION DETAILS:
+%% Why not \textit/bf/sc\bgroup and \egroup?
+% Well actualy that was the original solution. However this
+% doesn't differentiate between ending itallics or ending
+% boldface. The current solution does and this makes the
+% syntax more predictable and generally more useful.
+
+%% Why no ^^typewriter^^?
+% because this doesn't add much value, in most contexts
+% where a monospace font is useful there is already
+% other syntax available.
diff --git a/macros/latex/contrib/easyformat/easyformat.tex b/macros/latex/contrib/easyformat/easyformat.tex
new file mode 100644
index 0000000000..6cc49cd4d2
--- /dev/null
+++ b/macros/latex/contrib/easyformat/easyformat.tex
@@ -0,0 +1,290 @@
+% !TeX spellcheck = en_GB
+
+\documentclass[11pt, cm-default]{l3doc}
+% 11pt and keep on using the Computer Modern.
+% We want to maintain the original look of
+% our documentation so away with the coloured
+% links and references as wel ↓↓↓
+\hypersetup{hidelinks}
+
+\usepackage[british]{babel}
+\usepackage{microtype}
+\usepackage{easyformat}
+
+\def\labelitemi{--}
+
+\title{\pkg{easyformat}\\[.5em]
+ \large _the_ manual for the 2017/06/03 version (v1.4.0)}
+
+\author{Evert Provoost}
+
+\date{}
+
+\begin{document}
+
+ \maketitle
+
+ \begin{abstract}
+ \pkg{easyformat} is a package that allows the use of~|_| to begin/end _italics_ or __boldface__ and |^| to begin/end ^smallcaps^. As an alternative to the standard \LaTeX\ |\textit{italic}|, |\textbf{bold}| and |\textsc{smallcaps}|.
+ \end{abstract}
+
+ \tableofcontents
+ \newpage
+
+ %% NOT NEEDED.
+ % Insert a blank page.
+ %\null % The page has to contain 'something'.
+ %\thispagestyle{empty} % Hide the pagenumber.
+ %\addtocounter{page}{-1} % So the next doesn't turn 3.
+ %\newpage
+
+ \section{Introduction}
+ Usually when you want to make something _italic_ or __bold__ in \LaTeX\ you insert |\textit{italic}| or |\textbf{bold}| respectively.
+
+ However when writing a book or another text where this formatting is common, this quickly becomes annoying to type.
+
+ \begin{quote}
+ __Quick disclaimer:__\\
+ I'm not saying that the \LaTeX\ way is bad. I just want to explain that it's not ideal under all circumstances.
+ \end{quote}
+
+ Simple markuplanguages (eg. Markdown) have a more elegant solution.
+ If you, for example, wanted to write:
+ \begin{quote}
+ __Stop!__ You _have_ to wait!
+ \end{quote}
+
+ In Markdown, you'd type:
+ \begin{quote}
+ |**Stop!** You *have* to wait!|
+ \end{quote}
+
+ As you can see it's a matter of _wanting_ italic or bold formatting, adding~*'s where needed and done; no (long) macros to type.
+
+ With the help of \pkg{easyformat} we can do something similar, here we get the same result with:
+ \begin{quote}
+ |__Stop!__ You _have_ to wait!|
+ \end{quote}
+
+ (Why underscores? See: \ref{Why?!})\\
+
+ And since it is good practice to add abbreviations using ^smallcaps^, \pkg{easyformat} gives you |^smallcaps^|.
+
+ So:
+ \begin{quote}
+ |^nasa^ and ^esa^ are probably the best known space agencies.|
+ \end{quote}
+
+ Results in:
+ \begin{quote}
+ ^nasa^ and ^esa^ are probably the best known space agencies.
+ \end{quote}
+
+ \section{Usage, syntax and examples}
+ Like usual you import the package with: |\usepackage{easyformat}|
+
+ \pkg{easyformat} makes |_| an active character, however it was already `special' before so you still have to type~|\_| if you want to insert an underscore.
+
+ The same can be said of |^|, however since this one is difficult to add in ordinary \LaTeX, the \pkg{easyformat} package gives you |\cir| to get \cir.
+
+ \newpage
+
+ As already said, \pkg{easyformat} uses a Markdown-like syntax, so:
+
+ \begin{quote}
+ |_italic,_ __bold,__ ___bolditalic___ and ^smallcaps!^|
+ \end{quote}
+
+ Gives:
+ \begin{quote}
+ _italic,_ __bold,__ ___bolditalic___ and ^smallcaps!^
+ \end{quote}
+
+ However we can also do more complex stuff, eg.:
+ \begin{quote}
+ |_Lorem __ipsum_ totalem__ ^da^ __givea _zin_ doram__|\\
+ |_zet_tim, liefkan.|
+ \end{quote}
+
+ Becomes:
+ \begin{quote}
+ _Lorem __ipsum_ totalem__ ^da^ __givea _zin_ doram__ _zet_tim, liefkan.
+ \end{quote}
+
+ Those with a good eye might have noticed that \pkg{easyformat} adds italics correction when needed. Just like |\textit{zet}tim| would have.
+
+ \section{Troubleshooting}
+ \pkg{easyformat} tends to conflict with the loading of other packages, therefore you should probably load \pkg{easyformat} last.
+
+ \begin{quotation}
+ ``For some or other reason I get some weird formatting\dots''
+ \end{quotation}
+
+ It could be a bug---in which case I'd love to hear from you (see \ref{contact})---however, you probably forgot to close your formatting somewhere and because of how \pkg{easyformat} works you can get weird results.
+
+ %__Explanation:__ when you start eg. _italics_ with |_|, \pkg{easyformat} remembers the shape (the same is true for ^smallcaps^, when you start __boldface__ it remembers the series) of the font. When you get out of _italics_, it resets the shape (respectively the series) to what it was before the starting the formatting.
+
+
+ %% This is solved in version 2017/04/09 v1.1.0
+ %\subsection{Underscore in subtitles\label{undtitles}}
+ %If you ever try something similar to |\section{__Vectors:__ $\vec{F}_g$}|: \TeX\ will shout at you. Why? I don't really know. However I do know how to fix this. If we want to get the previous example we would use:
+
+ %\begin{quote}
+ % |\setundsub|\\
+ % % Yeah there's a glitch were the first is indented slightly more
+ % % unless there is something before the next lines......
+ % \hspace*{0pt}|\section{$\textbf{Vectors:} \vec{F}_g$}|\\
+ % \hspace*{0pt}|\setundact|
+ %\end{quote}
+
+ %This first resets the |_| character so it can only be used as the start of subscripts; then adds the subtitle and afterwards re-initiates |_| for __bold__ and _italic_. (Obviously the \pkg{easyformat}-syntax does not work _in_ the subtitle, so you'll have to use the \LaTeX-commands.)
+
+ \newpage
+
+ \section{Macros}
+ \subsection{Special characters}
+ \begin{function}{\cir}
+ \begin{syntax}
+ \cs{cir}
+ \end{syntax}
+ Insert a circumflex (\cir) character.
+ \end{function}
+
+ %%\subsection{Fonts}
+ % Removed in v1.4.0
+ %\begin{function}{\nrfamily}
+ % \begin{syntax}
+ % \cs{nrfamily}
+ % \end{syntax}
+ % Reverts the font family to the default.
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\nrshape}
+ % \begin{syntax}
+ % \cs{nrshape}
+ % \end{syntax}
+ % Reverts the font shape to the default.
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\nrseries}
+ % \begin{syntax}
+ % \cs{nrseries}
+ % \end{syntax}
+ % Reverts the font series to the default.
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setffamily}
+ % \begin{syntax}
+ % \cs{setffamily} \Arg{font family}
+ % \end{syntax}
+ % Quickly change the font family.
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setfshape}
+ % \begin{syntax}
+ % \cs{setfshape} \Arg{font shape}
+ % \end{syntax}
+ % Quickly change the font shape.
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setfseries}
+ % \begin{syntax}
+ % \cs{setfseries} \Arg{font series}
+ % \end{syntax}
+ % Quickly change the font series.
+ %\end{function}
+
+ \subsection{\pkg{easyformat}-syntax}
+ \begin{function}{\enableeasyformat}
+ \begin{syntax}
+ \cs{enableeasyformat}
+ \end{syntax}
+ Enables the \pkg{easyformat}-syntax.
+ \end{function}
+
+ \begin{function}{\disableeasyformat}
+ \begin{syntax}
+ \cs{disableeasyformat}
+ \end{syntax}
+ Disables the \pkg{easyformat}-syntax.
+ \end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setciract}
+ % \begin{syntax}
+ % \cs{setciract}
+ % \end{syntax}
+ % Sets the catcode of |^| to 13 (active).
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setcirsup}
+ % \begin{syntax}
+ % \cs{setcirsup}
+ % \end{syntax}
+ % Sets the catcode of |^| to 7 (superscript).
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setundact}
+ % \begin{syntax}
+ % \cs{setundact}
+ % \end{syntax}
+ % Sets the catcode of |_| to 13 (active).
+ %\end{function}
+
+ % Removed in v1.4.0
+ %\begin{function}{\setundsub}
+ % \begin{syntax}
+ % \cs{setundsub}
+ % \end{syntax}
+ % Sets the catcode of |_| to 8 (subscript).
+ %\end{function}
+
+ \section{Technical details}
+ \subsection{Why \texttt{\_} and not *?\label{Why?!}}
+ To make * work we would have to make it an active character, however this would break things like |\section*{Art}|. The~|_| is already protected by \TeX\ because of it's meaning in mathmode. However, it has little to no use in textmode. This is why we can use~|_| for this purpose and not~*.
+
+ \subsection{Does this break mathmode?}
+ No it doesn't. |_| and |^| keep behaving like before in mathmode, their meaning only changes in textmode. (We first check whether we are in mathmode or not and then behave accordingly.)
+
+ \section{Contact\label{contact}}
+ If you want to make suggestions or have any questions whose answer could be included in a future version of this document, you can email to this address: \url{mailto:evert.provoost@gmail.com}
+ \newpage
+
+ \section{Changelog}
+ We only include important changes from v1.0.0 onwards, since earlier versions barely worked.
+
+ \subsection*{2017/06/03 v1.4.0}
+ Improved code readability.
+ We now fully use \pkg{expl3}, which eliminates most of the possible future issues with \LaTeX3.
+ Fixed a kerning issue with |\cir| in mathmode.
+ Removed: |\setundact|, |\setundsub|, |\setciract|, |\setcirsup|, |\nrfamily|, |\nrshape|, |\nrseries|, |\setffamily|, |\setfshape| and |\setfseries| as these do not add any value to the package.
+
+ \subsection*{2017/05/28 v1.3.0}
+ Removed forced re-enabling of the \pkg{easyformat}-syntax at the start of the document.
+ Rewritten to use \pkg{expl3}, this makes the code shorter and a future move to \LaTeX3 easier.
+ Fixed an error that could occur with |\cir|.
+ \pkg{easyformat} now also behaves correctly when a fontpackage is loaded.
+
+ \subsection*{2017/04/17 v1.2.0}
+ Improved handling of mixed styles.
+ Added |^smallcaps^| for ^smallcaps^.
+
+ \subsection*{2017/04/09 v1.1.0}
+ Made usage of syntax in |\section{}|, and similar macros, possible. Changed the behaviour so it works more like |\emph{}| (this also simplifies the code).
+
+ \subsection*{2017/04/07 v1.0.0}
+ First stable version.
+
+ % Insert a friendly message :)
+ \vspace*{\fill}\noindent
+ Made with $\heartsuit$ in Berlaar, Belgium.
+ \clearpage
+
+\end{document}