summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/easyformat/easyformat.tex
blob: 6cc49cd4d29efa84ca949d8c568019e504d573c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
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}