summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/easyformat/easyformat.tex
blob: 78c8a0aa999838c4e33abcb84d65ef61ef35b81c (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
% !TeX spellcheck = en_GB

\documentclass[a4paper, 11pt]{article}
\usepackage[british]{babel}
\usepackage[hidelinks]{hyperref}
\usepackage{microtype}
\usepackage{easyformat}

\def\labelitemi{--}

\def\easyformat{\texttt{easyformat}}

\title{\easyformat\\[.5em]
		\large _the_ manual for the 2017/05/28 version (v1.3.0)}

\author{Evert Provoost}

\date{}

\begin{document}

	\maketitle
	
	\begin{abstract}
		\easyformat\ is a package that allows the use of~\verb|_| to begin/end _italic_ or __bold__ and \verb|^| to begin/end ^smallcaps^. As an alternative to the standard \LaTeX\ \verb|\textit{italic}|, \verb|\textbf{bold}| and \verb|\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 \verb|\textit{italic}| or \verb|\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}
		\verb|**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 \easyformat\ we can do something similar, here we get the same result with:
	\begin{quote}
		\verb|__Stop!__, you _have_ to wait!|
	\end{quote}
	
	(Why underscores? See: \ref{Why?!})\\
	
	And since it is good practice to add abbreviations using ^smallcaps^, \easyformat\ gives you \verb|^smallcaps^|.
	
	So:
	\begin{quote}
		\verb|^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: \verb|\usepackage{easyformat}|

	\easyformat\ makes \verb|_| an active character, however it was already `special' before so you still have to type~\verb|\_| if you want to insert an underscore.
	
	The same can be said of \verb|^|, however since this one is difficult to add in ordinary \LaTeX, the \easyformat\ package gives you \verb|\cir| to get \cir.
	
	\newpage

	As already said, \easyformat\ uses a Markdown-like syntax, so:
	
	\begin{quote}
		\verb|_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}
		\verb|_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 \easyformat\ adds italics correction when needed. Just like \verb|\textit{zet}tim| would have.
	
	\section{Troubleshooting}
	\easyformat\ tends to conflict with the loading of other packages, therefore you should probably load \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 \easyformat\ works you can get weird results.

	%__Explanation:__ when you start eg. _italics_ with \verb|_|, \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 \verb|\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}
	%	\verb|\setundsub|\\
	%	% Yeah there's a glitch were the first is indented slightly more
	%	% unless there is something before the next lines......
	%	\hspace*{0pt}\verb|\section{$\textbf{Vectors:} \vec{F}_g$}|\\
	%	\hspace*{0pt}\verb|\setundact|
	%\end{quote}
	
	%This first resets the \verb|_| character so it can only be used as the start of %subscripts; then adds the subtitle and afterwards re-initiates \verb|_| for %__bold__ and _italic_. (Obviously the \easyformat\ syntax does not work %_in_ the subtitle, so you'll have to use the \LaTeX-commands.)
	
	\section{Macros}
	\subsection{Special characters}
	\noindent\fbox{\texttt{\textbackslash cir}}
	Insert a circumflex (\cir) character.

	\subsection{Fonts}
	\noindent\fbox{\texttt{\textbackslash nrfamily}}
	Reverts the fontfamily to the default.\\

	\noindent\fbox{\texttt{\textbackslash nrshape}}
	Reverts the fontshape to the default.\\

	\noindent\fbox{\texttt{\textbackslash nrseries}}
	Reverts the fontseries to the default.\\

	\noindent\fbox{\texttt{\textbackslash setffamily\{_fontfamily_\}}}
	Quickly change the fontfamily.\\

	\noindent\fbox{\texttt{\textbackslash setfshape\{_fontshape_\}}}
	Quickly change the fontshape.\\

	\noindent\fbox{\texttt{\textbackslash setfseries\{_fontseries_\}}}
	Quickly change the fontseries.
	
	\subsection{\easyformat\ syntax}
	\noindent\fbox{\texttt{\textbackslash enableeasyformat}}
	Enables the \easyformat\ syntax.\\
	
	\noindent\fbox{\texttt{\textbackslash disableeasyformat}}
	Disables the \easyformat\ syntax.\\
	
	\noindent\fbox{\texttt{\textbackslash setciract}}
	Sets the catcode of \verb|^| to 13 (active).\\
	
	\noindent\fbox{\texttt{\textbackslash setcirsup}}
	Sets the catcode of \verb|^| to 7 (superscript).\\
	
	\noindent\fbox{\texttt{\textbackslash setundact}}
	Sets the catcode of \verb|_| to 13 (active).\\
	
	\noindent\fbox{\texttt{\textbackslash setundsub}}
	Sets the catcode of \verb|_| to 8 (subscript).
	
	\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 \verb|\section*{Art}|. The~\verb|_| 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~\verb|_| for this purpose and not~*.
	
	\subsection{Does this break mathmode?}
	No it doesn't. It keeps behaving like before in mathmode, it's meaning only changes in textmode. (We first check whether we are in mathmode or not and 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/05/28 v1.3.0}
	Removed forced re-enabling of the \easyformat-syntax at the start of the document.
	Rewritten to use \texttt{expl3}, this makes the code shorter and a future move to \LaTeX3 easier.
	Fixed an error that could occur with \verb|\cir|.
	\easyformat\ now also behaves correctly when a fontpackage is loaded.

	\subsection*{2017/04/17 v1.2.0}
	Improved handling of mixed styles.
	Added \verb|^smallcaps^| for ^smallcaps^.

	\subsection*{2017/04/09 v1.1.0}
	Made usage of syntax in \verb|\section{}|, and similar macros, possible. Changed the behaviour so it works more like \verb|\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}