% !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/04/09 version (v1.1.0)}

\author{Evert Provoost}

\date{}

\begin{document}

	\maketitle
	
	\begin{abstract}
		\easyformat\ is a package that allows the use of~\_ to begin/end _italic_ or __bold__ formatting as an alternative to the standard \LaTeXe\ \verb|\textit{italic}| and/or \verb|\textbf{bold}|.
	\end{abstract}

	%\tableofcontents % NOT NEEDED
	\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?!})
	
	\section{Usage, syntax and examples}
	Like usual you import the package with: \verb|\usepackage{easyformat}|

	\easyformat\ makes \_ an active character, however it was already 'special' before so you still have to type~\verb|\_| if you want to insert an underscore.

	As already said, \easyformat\ uses a Markdown-like syntax, so:
	
	\begin{quote}
		\verb|_italic,_ __bold,__ and ___bolditalic!___|
	\end{quote}

	Gives:
	\begin{quote}
		_italic,_ __bold,__ and ___bolditalic!___
	\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 italicscorrection when needed. Just like \verb|\textit{zet}tim| would have.
	
	\section{Utilities}
	%% This is solved in version 2017/04/09
	%\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 \_ 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 \easyformat\ syntax does not work %_in_ the subtitle, so you'll have to use the \LaTeX-commands.)
	
	\subsection{\texttt{\textbackslash nrshape}}
	Reverts the fontshape to the default.
	
	\subsection{\texttt{\textbackslash nrseries}}
	Reverts the fontseries to the default.
	
	\subsection{\texttt{\textbackslash setundact}}
	Sets the catcode of \_ to 13 (active), effectively _(re-)enabling_ the \easyformat\ syntax.
	
	\subsection{\texttt{\textbackslash setundsub}}
	Sets the catcode of \_ to 8 (subscript), effectively _disabling_ the \easyformat\ syntax.
	
	\section{Technical details}
	\subsection{Why \_ 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~\_ 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. 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}
	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/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}
