LaTeX for PhD students

Today, I decided to finally publish some thoughts on why I think PhD students can profit from using LaTeX. In this post, I try to avoid common not-all-that-creative reasons and point you to some aspects you might not yet have thought about like the fact that your PhD thesis will yield two PDF outputs with (more or less) the same content but very distinct different formatting requirements. Enter LaTeX.

1 PhD = 2 (!) print outputs, i.e. thesis print and printed book publication

Typesetting your PhD in LaTeX is a good idea because of the citation management, for formulars and for images. You probably already know that. But another aspect a lot of people tend to forget while writing their PhD thesis is that a thesis will usually result in two different output PDFs with different typesetting needs: The thesis to be handed in at your university and the print publication which follows. But these two usually have some important differences in requirements. Like a thesis print will probably be a4 or letter paper, a font size of 12pt, etc. A print publication almost always has a smaller paper size and thus, a smaller font size. In my case, this was: paperwidth=170mm, paperheight=240mm and 11pt. Where as a4paper is 210:270, as far as I remember. If you take this into account beforehand, you can save yourself a lot of work and trouble. Also, it’s not like you will suddenly have tons of free time in the time after the PhD writing, probably the opposite. You don’t want to make that even harder by placing another unnecessary burden on yourself.

Already here, LaTeX really pays of. Just change two settings. That’s basically less than 10 characters (!) in your main.tex. If you don’t have to make other changes, that is. Well, you get what I mean. Whereas in MS Word, this can be a lot of effort since quotes probably have a different text size and unless you use the “Standard” predefined templates which you can then change, this can take you a while. Also, it probably often happens to people who don’t reflect on the typesetting while writing (which, after all, will occur long after the writing, so we don’t yet give it a lot of thought) that you don’t consistently use those templates and thus, will have to change or at least check everything manually. With LaTeX, you don’t. Isn’t this enough of a point for LaTeX already? But behold, we have more.

 

Typesetting concerns like orphans and widow lines

Another thing for producing nice typesetting: A (respectable) publisher will usually ask you to take care of orphans and widow lines. In a 300 page MS Word document, you will probably end up having to do this all manually which usually entails all sorts of horrible consequences you hadn’t even dreamt about this far. While this problem cannot be fully automated in LaTeX, you have the possibility of adding this simple statement to your preamble:

\setlength{\emergencystretch}{.25em} % avoid line overflow
\clubpenalty10000\widowpenalty10000\displaywidowpenalty=10000% avoid widow lines and orphans

This, supposing that you have included all the languages you use with \usepackage[ngerman,english]{babel} (for example, last one is the one active), will avoid most line overflows.

A problem that you, admittedly don’t have in MS Word but do have in LaTeX. But more important is the following line. There, we add to the internal ‘penalties’ which LaTeX has, thus preventing orphans and widow lines quite effectively. Maybe you’ll still have to correct one or two things. But one or two things in the whole document, speaking of a document wihch basically handles itself, is not that much of a big deal. In MS Word, calculate to sit down for a few hours. Thus, yet another plus for LaTeX: less grey hair and more time for work-life-balance. Isn’t it amazing?

 

Another plus: Relative and absolute positioning

It’s always better to use relative positioning and values and also, leave litterally everything up to LaTeX. Thank me later. For some info on relative and absolute sizing, consult the upcoming post LaTeX for Archaeologists: Typeset your PhD catalogue in LaTeX post.

 

The (lack of) comment function: A workaround

A possible down-side for LaTeX is that advisors often like to use the comment function in MS Word to correct and comment your work in progress. This, I personally have solved by converting it to MS Word using Pandoc and then uploading it to GoogleDocs for my advisor to make corrections. These have to be put back into the original by hand, of course. But you need to proof-read multiple times anyway, so I reckon it doesn’t make much of a difference. It’s a wee bit inconveniant, is all.

But… LaTeX is scary?! On common concerns

If the prospect of first “having to learn complicated LaTeX” sacres you, you might want to check my article on The power of simplicity, or: Why LaTeX needn’t be scarily complicated. If you think LaTeX will slow you down, you might want to check my post on typing fast in LaTeX. But then again, when writing highly qualitative work (like your dissertation should be), it might even be better if your writing slows you down a little. Pause to reflect!

Transition to LaTeX and get a life. A manifesto

“Well, at some point, LaTeX really had more features than Word but nowadays, I don’t see why you should bother using it anymore.” That’s a typical counter-argument, a justification why people don’t use LaTeX and don’t see why it’s worth the effort to learn it and finally make the transition. To this, I want to say: Well, can it do this? Hint: no. I rather suggest you don’t even try. Well at least, don’t hold me accountable if you should try and fail.

If you don’t see why using LaTeX would benefit you, maybe you just haven’t heard the facts yet? And well, probably you aren’t an archaeologist with 1 million images in a 500-page PhD thesis. If you are, don’t commit suicide just yet. There are other ways than Word. If your thesis document won’t even open anymore, don’t despair. Just convert it to LaTeX! And, thank me later.

Citation styles

LaTeX offers citation support. It’s basically a lot like Citavi or Zotero, only less complicated. Not that I have a lot experience with those, I do admit it. But the principle is the same. LaTeX and Bibtex seem complicated at first. But you’re most certainly just so conditioned and accustomed to MS Word workflows that you don’t remember anything else. And what we don’t know, we fear. But you need not fear, LaTeX is here for you.

A tutorial and more info on this will follow in a separate post.

Yes, LaTeX will throw warnings and errors. It’s not a big deal, really.

People are put off by the fact that you can get warnings or fatal compilation errors. Well yeah, it’s inconvienent to have to debug your own bullshit but well, sorry to have to break it to you, that’s life. Would you rather have a program that doesn’t complain there is a mistake, subsequently hide the problem from you entirely but just stop working for inexplicable reasons and you have no way of escaping? Wait, yes, maybe you do. It’s called MS Word.

You’re not a qualified typesetter

LaTeX is an art. It’s supposed to be an art. Typesetting is an art. And if you haven’t learned to be a typesetter, you probably are not and thus, should not act as a professional typesetter. But MS Word, one hell of a program (and I mean this litterally), makes you believe that you are or you could. It even suggests you should. Hint: You shouldn’t. And in your heart, you really know that’s true.

How to transition from an existing MS Word document or LaTeX-ify your workflow

  1. Migrate your document. (Oxgarage, Pandoc, you name it. Read how to do this in my post on who to quit MS Word).
  2. Continue writing in Word and transform your stuff to LaTeX before adding the images and thus, killing Word for good. Why the hell would anyone want to continue using MS Word? But hey, my opinion isn’t the truth. It’s just my opinion. Do what works for you. If it contains LaTeX, all the better. The LaTeX Noob uses this workflow and it seeems to work for her. Kind of like a “the best of the two worlds” compromise. You get the parts where MS Word is conveniant (letting your advisor use the comment function, etc.), but the typesetting and image handeling is done in LaTeX.
  3.  Just write it in LaTeX. It’s just a question of getting used to it. Using it exclusively will give you just that. Even though I had been using LaTeX for years, transitioning completely made me quite a bit better still. I now also write quick notes in LaTeX without batting an eyelash. Sometimes I still use a GoogleDoc to write things down that are just meant for note-taking, not for creating PDF output.

I will follow up with a post on citation styles and how to import your Citavi to BibTeX, etc. Until then, consider looking up some of my already existing posts which might be of interest, like Jumpstarting: Learn LaTeX in 3 minutes  or A Humanities’ seminar paper with LaTeX – in 10 minutes or How to quit MS Word for good.

Best,

your Ninja

Further resources

The not-so-short intro, also available in German. Tobias Oetiker, Hubert Partl, Irene Hyna & Elisabeth Schlegl: The Not So Short Introduction to LATEX 2ε. Or LATEX 2ε in 139 minutes. Version 6.2, February 28, 2018

https://www.latex-tutorial.com/tutorials/

https://learnxinyminutes.com/docs/latex/

https://en.wikibooks.org/wiki/LaTeX

A Survival Guide for a PhD: http://karpathy.github.io/2016/09/07/phd/

https://www.quora.com/I-wrote-my-PhD-dissertation-in-LaTeX-but-my-advisor-told-me-it-needs-to-be-in-a-format-other-than-PDF-to-send-to-my-committee-members-He-says-it-is-too-difficult-to-make-comments-or-corrections-on-PDF-What-is-the-best-format-for-a-dissertation Quote: “And I’ll even print out the occasional paper and use a red pen. ” yep, good idea. I thought that was actually very sensible advice 😉

https://tex.stackexchange.com/questions/1756/why-should-i-use-latex

https://www.overleaf.com/project/5c42fa03a343e77a02003def (The Scientific Paper: A Template with Tips for Working with LaTeX)

 

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

Advertisements

Hipster CV – A Template

Dear all,

sorry you haven’t been hearing from me so much lately. It’s been quite busy. To make it up to you, I wanted to share my hipster CV template on this occasion 😉 I will probably explain it later and also probably modify it in a way that it’s easiert to use for a beginner. If you want to use it and but don’t feel comfortable with how the template works, just check where the text you are looking to replace is in the main.tex and replace it with your content. That way, you should get away with fairly limited LaTeX skills and still be able to use the template if you want it.

hipster-cv

 

It is available on the newly created LaTeX Ninja Github! The template is not exactly the same as shown in the Teaser: LaTeX Resumé Template Preview.

hipster-cv-github

 

So you can look forward to more versions which will be kind of the same style. But I now have so many different elements that I could fill at least 10 different CV templates. Since I didn’t want to fall victim to my own perfectionism, I dedided to share the template now even though it could probably be better. It also doesn’t really comply with my own standards regarding good code, etc. 😉 Well, you can’t always have it all.

It is, however, more of a Saturday afternoon fun thing I did. I won’t give any recommendations as to whether it will be considered as appropriate in your field of work to actually use this CV 😉

Also, I hope I am allowed to have the Jack Sparrow images in the example. I am not so sure about it however. Come visit me in prison if this should go wrong 😉

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

Floating minipages and other wizardry

Inspired by a current issue from my friend the LaTeX Noob, I wanted to give a short explanation on how you can combine floats (i.e. figures) and minipages. Why should you care? Well, if you need tikzpicture or images placed besides eachother or beside text. So most people will probably need this at some point 😉 A great resource is the WikiBook, as always. If you want the lengthy account – that’s the way to go. For everybody else, an explanation of my own.

Floats and non-floating boxes

What are floats?

Some fundamental explanations first: A figure is a float. A minipage is not a float but a box which sits at its fixed place. These are two fundamentally different things. When you combine them in a bad way, LaTeX might get fed up at this. So when planning your minipaging or floating situation, ask yourself which effects are really important to you and which aren’t.

Do I even need a float?

A float will self-regulate positioning pretty much. If you need this feature, you need a float. But maybe this is a behaviour you explicitly don’t want anyway. Then maybe you don’t even need a float at all. Beginners often get confused and think they need to use figures everywhere but, strictly speaking, you don’t. You can, for example, just \includegraphics without a figure. Then the thing will just not have floating behaviour and you also might want captions and stuff, so an environment might be in order. But this need not be a figure. But if you don’t want all this, be aware that you might not need a figure at all and save yourself some trouble debugging.

I would suggest you probably go for figures anyway if it’s a long document where positioning might change dramatically after you first insert the picture, minipage or whatever. If, however, your result is pretty static and not a pages long document, you might just be better off leaving out the floats completely. Like, for example, in a poster, positioning isn’t really up for LaTeX to decide. You need it placed in a stable, reliable way and the way you want it and you exert lots of ‘control’ over the whole process.

Floats are better if you are dealing with a thing whose behaviour LaTeX is supposed to regulate acccording to its own best judgement. And as we all know, LaTeX’s judgement is pretty awesome. So this is a feature you might very well want to profit from in most cases. Also, you might want a \listoffigures. Or not. So think about that.

A little rant on “LaTeX is not doing what I want”

Beginners often get fed up with this behaviour because “LaTeX is not doing what I want”. This is probably due to the fact that you are using structures you think are supposed to do XYZ while they actually are programmed to do ABC. This is just a ‘misunderstanding’ between LaTeX and the user and can be remedied by additional knowledge about how some things work internally. So a general good bit of advice would be to look up how a structure you are trying to use is programmed to work internally. Most of the time, looking up the official documentation will already suffice. Probably it is supposed to do something completely different than what you thought it was or wanted it to. This is not LaTeX’s fault. It’s the fault of the user who doesn’t bother to look up those basic functionalities, so don’t blame LaTeX. But of course, if you’re still a beginner, this is a normal thing to do or expect. A common false assumption among programming novices. So don’t worry either. Next time you will know what to do.

A computer will do what you wrote down. Not what you meant. Even and especially, if the two are not the same thing 😉

The objective: placing things side by side

We will follow up with some examples of figures and minipages. By now, you are already informed what the differences are and can make an intelligent choice 😉

Case 1: The figure placed right here

The following is just a figure, but it will be forced to be placed right here (as indicated per the H). Using a small h really only means ‘here if it fits’. Only h! or H actually mean HERE!!!Also, read this great (lenghty) information on floats if you want to know more. Don’t forget to \usepackage{float} if you want to use the H. Edit: Thanks to Karl from LaTeX ref who informed me that h! basically only sometimes accidentally results in “place it HERE”. Use H for reliability.

So depending on your other needs (\listoffigures, etc.), you might as well have not used a floating environment since obviously, you did not intend for the thing to float.

\begin{figure}[H]
    \centering
     \begin{tikzpicture}
    \basesketch\bfseries
    \angles
    \end{tikzpicture}
    \caption{Sketch}
    \label{fig:Sketch}
\end{figure}

Case 2: Figure beside text with wrapfigure

The same thing like with minipage, basically, can be achieved with a wrapfigure, which you might need at some point too. This will make an image float beside text. On this, read the Overleaf tutorial.


\begin{wrapfigure}{R}{0.3\textwidth}
    \centering
    \begin{tikzpicture}[opacity=0.8, scale=0.5]
    \basesketch \angles
    \filldraw[draw=black, fill=lila, fill opacity=0.3] (A) -- (B) -- (C) -- cycle;
    \filldraw[draw=black, fill=myblue, fill opacity=0.3] (A) -- (C) -- (K2) -- (K1) -- cycle;
    \end{tikzpicture}
    \caption{T\textsubscript{1} und T\textsubscript{2}}
    \label{fig:Triangles}
\end{wrapfigure}

Case 3: lifesaving minipages

First, I’ll explain the basic functionality of minipages and then issue some personal tips on how to use them 😉

Options

As you might have noticed, you have options when configuring your minipage: \begin{minipage}[adjusting]{width of the minipage} are the available ones. Meaning minipage has a specified alignment and a predetermined width. Although, you can use relative widths, of course. So it can be {3cm} or {0.3\textwidth} according to your needs. Notice however, that you cannot use 100% textwidth in total while still having everything aligned. Take off 0.03 in total to be sure. So all your minipages which are placed side by side cannot take up a total of 100% of the textwidth.

c = center, t = top and b = bottom are the alignment choices. c is default, I mostly use t. It can be a bit difficult to grasp what they actually do. They specify at which line the content gets aligned. So t means, the alignment will be oriented on the topmost, so the highest line.

Also, we can add more options [t][3cm][b] which additionally says that we have a fixed height of 3cm and the content will be aligned at the bottom. The (multiple) minipages themselves will be aligned at their tops.

Alignment of multiple minipages

Also, if you want multiple minipages aligned at their sides and not below eachother, you can’t have blank lines between them. Inside the minipage environments is no problem, but not following the first one before the second one, for example. See also Sasha Frank’s page and this.

When you check StackOverflow “How to use a figure inside a minipage” – the short answer is: You don’t!


\begin{figure}[ht]
  \begin{minipage}[b]{0.45\textwidth}
  \centering
    \includegraphics[width=\textwidth]{img1}
    \caption{blabla}
    \label{fig:fig1}
  \end{minipage}
  \hspace{0.5cm}
  \begin{minipage}[b]{0.4\textwidth}
    \centering
    \includegraphics[width=\textwidth]{img2}
    \caption{mycaption}
    \label{fig:fig2}
  \end{minipage}
\end{figure}

If you want to make two floats happily float, but in a row beside eachother, you can use the floatrow package, as detailed in this StackOverflow post.

Do I need a float now or what? Combining figure and minipage

If you don’t insist on having a float, people would probably go for minipage to make things sit aligned besides eachother and connected.

It is also not necessary to place your \includegraphics inside a figure, though a lot of beginners think so. Just put your images directly in a minipage if you don’t need floating behaviour. If you do – add a float. But not inside the minipage, this will cause an error. If you are confused about this, imagine a rubber duck floating in your bathtub. You cannot place it into a box because then it will sink. You can, however, make it carry a box on its back. So, this is basically the same thing with floats an minipages 😉

You cannot have a figure (=float) inside a minipage (non-floating box) since it will make the rubber duck sink. Don’t sink your rubber duck! Read up on it here (just to warn you, they don’t use rubber ducks for explanation, so don’t be disappointed).

And, by the way, it also doesn’t make sense to have float inside a fixed box. Float means, LaTeX decides where exactly to place elements. But if you put a fixed box, you have already made that decision. Nothing left for LaTeX to decide. Meaning LaTeX will go and sulk at you. If you need LaTeX to calculate where to put things and it is possible your document will change a lot, it’s better to use floats. If you want everything exactly where you want it, float will make you go crazy. You can put tikzpicture inside minipages. It’s confusing, I know.

And remember: If you don’t want the minipages to become “disconnected”, which is usually the case, make sure you don’t put an empty line after one of them. They should be “connected” in the code if you want them connected in the output.

Another example (snippet) from my personal CV template to visualize language skills. As you can see, you might be able to achieve what you want using a tabular as well.

cv-languages

This is how the code looks like:


\newcommand{\icon}[3]{\phantom{x}{#3\color{#2}#1}\phantom{x}}
%------------------- pictogram Fraction: pictoFraction
\newcommand{\pictofraction}[6]{%
\pgfmathparse{#3 - 1}\foreach \n in {0,...,\pgfma<span 				data-mce-type="bookmark" 				id="mce_SELREST_start" 				data-mce-style="overflow:hidden;line-height:0" 				style="overflow:hidden;line-height:0" 			></span>thresult}{\icon{#1}{#2}{#6}}%
\pgfmathparse{#5 - 1}\foreach \n in {0,...,\pgfmathresult}{\icon{#1}{#4}{#6}}%
}

\begin{minipage}[t]{\leftcolwidth}
\begin{tabular}{l | ll}
\textbf{German} & C2 & {\phantom{x}\footnotesize mother tongue} \\
\textbf{English} & C2 & \pictofraction{\faCircle}{blue}{3}{blue}{1}{\tiny}\\
   \textbf{Latin}  & C2 & \pictofraction{\faCircle}{blue}{3}{blue}{1}{\tiny}\\
   \textbf{French} & C2 & \pictofraction{\faCircle}{blue}{3}{blue}{1}{\tiny}\\
   \textbf{Ancient Greek} & B2 & \pictofraction{\faCircle}{blue}{3}{grey!30}{1}{\tiny}\\

\end{tabular}
\end{minipage}

There also is the subcaption package (subfigure or subfig are deprecated). Here, you can use sub-floats inside a single float. Here is an example of how to use it.

You can also put minipages inside a float, to make the whole thing float again. And that’s about it 😉

And just for your reference, I included the actual TikZ at the bottom of the post. Just in case you wanted it or whatever 😉

I really love minipages. They are my go-to thing for anything and everything. Sometimes even when there probably would be another (better) option available. Minipages rock! And so do you!

Best,

the LaTeX Ninja

The TikZ

\newcommand{\basesketch}{%
\scriptsize
\node[](Kreismittelpunkt) at (0,0) {};
\node[](K1) at (0,6) {};
\node[](K2) at (4,5) {};

\draw[] (Kreismittelpunkt) -- ++(0:5cm) node[](C){} -- ++(0:5cm) node[](K2){};
\draw[] (Kreismittelpunkt) -- ++(30:4cm)  node[](A){}  --  ++(30:2cm)  node[](B){}  -- ++(30:4cm) node[](K1){};
\draw[] (K2) -- (K1);
\draw[fill=myblue] (K2) circle (2.5pt) node[below=0.5em]{K\textsubscript{2}};
\draw[fill=myblue] (K1) circle (2.5pt) node[above=0.5em]{K\textsubscript{1}};

\draw[fill=myblue] (A) circle (2.5pt) node[above=0.5em]{A};
\draw[fill=myblue] (B) circle (2.5pt) node[above=0.5em]{B};
\draw[fill=myblue] (C) circle (2.5pt) node[below=0.5em]{C};
\draw[] (A) -- (C);
\draw[] (C) -- (B);
\draw[] (B) -- (K2);

% coordinates
\coordinate (K2) at (K2);
\coordinate (K1) at (K1);
\coordinate (A) at (A);
\coordinate (B) at (B);
\coordinate (C) at (C);

\draw[fill=myblue] (Kreismittelpunkt) circle (2.5pt) node[below=0.5em]{K};

% Alternative zu Arc zwischen zwei Punkten
\draw[-,draw=black!70] (K2) to[bend right=12] (K1);
\pgfresetboundingbox}

\newcommand{\angles}{%
\pic[draw=black!70,text=black!70, -,"$\alpha$"] {angle =A--C--Kreismittelpunkt};
\pic[draw=black!70,text=black!70, -,"$\delta$", angle eccentricity=1.3] {angle= B--C--A};
\pic[draw=black!70,text=black!70, -,"$\alpha$"] {angle = K2--C--B};
\pic[draw=black!70,text=black!70, -,"$\alpha$"] {angle = C--B--K2};

\pic[draw=black!70,text=black!70, -,"$\beta$"] {angle = A--B--C};
\pic[draw=black!70,text=black!70, -,"$\beta$"] {angle = K2--B--K1};

\pic[draw=black!70,text=black!70, -,"$\gamma$"] {angle = K1--K2--C};
\pic[draw=black!70,text=black!70, -,"$\gamma$"] {angle = B--K1--K2};

\pic ["\Huge $\cdot$", draw, -] {angle=C--A--B};
\pic ["\Huge $\cdot$", draw, -] {angle=Kreismittelpunkt--A--C};}

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

[Guest Post] Confessions of a LaTeX Noob

I am happy to introduce my first guest post on this blog. It’s from my archaeologist friend whom we decided to call “the LaTeX Noob” here. She will give her perspective on how using LaTeX in the Humanities feels for her and the problems she has encountered. Like how getting help can be tricky, you don’t want to look like an idiot and how you constantly have to defend your choice to use LaTeX (to users and non-users alike). “Why would a Humanities person want to use LaTeX anyway? You don’t need it and you’re not up for it” are the most common insults a Humanities person might have to endure after choosing LaTeX.

 

Here come the confessions of a LaTeX Noob:

Confessions of a LaTeX Noob

Okay, here I am, the LaTeX noob. Well, not that noob-noob, but noob nonetheless. I am an archaeologist and I am trying to write my thesis in LaTeX. Well, my catalogue, to be exact, because we archaeologists like pictures of our stones and potsherds and whatsoever.
So, we need a good tool to achieve a really nice looking result document. And no, I don’t have the money or the skills for Adobe or anything like that.
Have you ever tried to get a nice document done with Word, including lots of pictures? Yes, there is a good chance you will kill yourself trying. So, that is why I am here, busy reading the Ninja’s blog and her tutorials. I like the way she explains things (to me, also in our lunch and coffee breaks at university) and I really trust her on that issue. Mainly, because I cannot talk computer-talk and she understands my archaeologist-talk, because she is one of us.
So, why am I writing my first guest post on this blog? As a LaTeX noob, you are willing to try this new way of getting nice results in your writings, articles, and so on, BUT: It is neither simple nor easy to ask for help. Or trying to. Or showing your code to others.

Fear of being dumb

Okay, this might sound a little like overreacting, but yeah, asking for help in some online forum or even colleagues and friends who are skilled with LaTeX (and some of my friends and colleagues indeed did to write their thesis in LaTeX) is not that easy. Especially not if you are like me – always trying to find your own way, your own solution. But it is obvious that you will reach the point where you have to ask for help. After all, this is teamwork, right? I know, maybe this is sort of naive, but I always learned that I have to ask others, because they have different skills and knowledge and can help me, and I can help them in return. So, I just asked my questions… And then, a lot of nasty answers followed.

Sometimes, people are just suggesting what they mean using short terms or abbreviations – so, I have to google it, because simply writing that I am a LaTeX noob does not get across to them. If I repeat my question stating (the obvious) that I have no idea what they are talking about, some get really upset, writing that noobs and beginners should not even try because they have no idea of the matter. It gets worse when I tell them that I am an archaeologist, so, a girl of bones and sherds. This means, humanities. And hello, one of the greatest cliches around us: What do we need LaTeX for? We are no technicians. I will not argue about that. I took some university courses in programming, I can use QGIS and I know how a database should work and how I would have to build it, but I would not strictly need that stuff in my area of research, that is correct.

So, I might have heard about some things, but not all. And not all things I have heard about are logical to me. Arrogance does hurt. Noobs and beginners like me are tryng to learn. So, be kind. I sometimes try to talk to this kind of people… never mind. It does not help very often. But, I have to say, there are a lot of friendly people in the same online forum who tried to help and who sent a lot of tutorials. There is hope!
But mainly, I just felt dumb and stupid and I quit my experiments everytime, because I thought that it is not worth my time trying to get better and to do something good with LaTeX if there are that many unfriendly people out there. It sometimes felt like they did not want to be nice or help at all.

 

Confusion

No one ever said that LaTeX was easy-cheesy, but you have to admit that some coding is just not logical. How to put text and figures in the right connection, wondering why the whole thing is just a mess – until I stumbled upon the problem of floats (where it got even worse). Floating and non-floating, figures and minipages, and so on. I got really stuck there, it took me lots of hours to figure out what the differences were and how I can use both in combination.

It gets even harder, when skilled LaTeX-people are asking you about your work. You describe your way and your solution – and find yourself bombed with suggestions and new variations of packages you never ever heard of. And even trying to make your point clear does not really help sometimes. So, I just remain quiet, listening and somehow my brain gets totally winded up in knots and funny question marks in very bright colors. I asked them to write their suggestions down or to send me an example – most of them promised, but never did, and we never ever talked about that subject again. So, if you just want to show me how good you are, fine. But I really wanted your help, otherwise, I would not have started the conversation at all. If I do not want your help, I will tell you.

Feeling misunderstood

And then, there are people who think that you are exaggerating trying to use LaTeX, mainly because no other person they know has used it. They will even tell you every time they see you that you are wasting your time. You should be writing your thesis, not surfing the net and looking up funny lines of code. I had to invest all my energy on my genetically predisposed stubbornness to lock them out out of the room and to figure out my needed piece of code.Then I present it and they are really surprised (well, most of them). Some remain sceptical and even tear your work apart, because they have worked and are working in a different way and, of course, it is only correct if done their way.

 

Fear of doing things wrong

I have still to fight that one. As for now, my document looks nice and is working, so after all, it is functioning – no errors mean everything’s good, right? Still, there are people who are telling you that you code is not clear, not logical or far too complicated. BUT: It can’t be completely wrong. It works, after all.
Okay, I might have a very strange style, but that is okay for me, as long as everything works that way I want it to work. I somehow think about coding style as a fashion issue. So my coding may not be fashionable, but I think it is like cosy underwear: I might not want to show it to people. But hey, it feels good to me.

 

Getting rid of my image as a LaTeX-Noob

I sometimes wonder when I will get rid of my image as a total noob. I might not be a beginner anymore because I can read tutorials, even advanced ones, and I can understand them and I can follow them and reproduce them myself on my terms and  conditions. But, I am still a noob. Maybe I will always be a noob, concerning some people out there who are basically LaTeX-gods. But at least I have a LaTeX Ninja among my friends. She will show me how I can survive.
So, this is my first post here. In my next one, I will write about my writing and my time management – and my motivation vs. my iron discipline on how to write 130 pages a month, neither loosing my nerves or my mind, nor killing anyone (including my laptop).

 


 

So, this is it for now. Thanks for reading, as always.
Cheers,

the LaTeX Ninja

PS: By the way, she prepared this post in LaTeX 😉

XML to LaTeX (simple)

Today, I wanted to share this super simple XML to LaTeX tutorial. Using XSLT, you are going to transform XML data to LaTeX output which you can then go on to compile into your desired output PDF. There will be no fancy stuff whatsoever in this post, just the basics and what to keep in mind with these transformations. It is the quick intro to XML to LaTeX I did with my students a while ago which was done one day after they had their first contact with XSLT, so it should really be beginner-friendly. I labeled it “Advanced LaTeX” anyway because I think starting to automate things is always a step in the right direction 😉

Configuring the transformation scenario in Oxygen

I am going to assume you use Oxygen now because that’s what a lot of people in the DH do and this post is directed towards my friends in the DH. Especially those who think print editions are an obsolete concept in times of the Digital Edition. Maybe having a nice little intro to XML to LaTeX transformations available will change their minds 😉

To set up the transformation scenario, choose XML transformation using XSLT, then choose your XML document and your XSL stylesheet (set up and open those document in the editor before you configure the scenario). Then choose a Saxon 9 version (whichever you like). Then ignore the FO tab and get right to the output tab.

Here you configure how to name your output. Best click the green arrow and choose cfn, then append -latex.tex. So the result the current filename with -latex.tex appended to it. This is an important step so you don’t accidentally overwrite the original. Which in this case is not so dramatic since it has a different ending anyway but if you do XML to XML transformations, this is even more crucial. Then tell Oxygen to show it in the editor as XML (even though you know it isn’t). The editor will then, of course, complain about the non-valid XML but don’t worry. Just copy all (CTRL+ACTRL+C) and paste it (CTRL+V) into a completely empty (!) project in Overleaf  or just compile the LaTeX directly if you have it installed on your machine.

There it is, you’re set. Now let’s get to the stylesheet.

The stylesheet

So, this is the whole thing. You can just grab it and go if you don’t care for the explanation or read on to find out why things were done the way they were done. This tutorial assumes you’re already familiar with how XSLT works, just haven’t done transformations to LaTeX yet, by the way. I am also assuming, your base XML is in the TEI standard.

 

 

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"     xmlns:xs="http://www.w3.org/2001/XMLSchema"     xmlns:t="http://www.tei-c.org/ns/1.0"     exclude-result-prefixes="xs"     version="2.0">
    <xsl:strip-space elements="*"/>
    <xsl:output method="text" encoding="UTF-8" indent="no" omit-xml-declaration="yes"/>

    <xsl:template match="/">
        <xsl:text>\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\DeclareUnicodeCharacter{2060}{\nolinebreak} % might not be necessary for you

\title{</xsl:text><xsl:apply-templates select="//t:title"/>
        <xsl:text>}
\author{</xsl:text><xsl:apply-templates select="//t:author"/>
        <xsl:text>}\date{\today}
\begin{document}
\maketitle
\tableofcontents\newpage</xsl:text>
        <!-- get some metadata from the TEI header using the push paradigm -->
<xsl:text>\begin{itemize}</xsl:text>
<xsl:for-each select="//t:persName[ancestor::t:teiHeader]">
    <xsl:text>\item </xsl:text>
    <xsl:value-of select="." />
    <xsl:text>

    </xsl:text>
</xsl:for-each>
<xsl:text>\end{itemize}
\newpage</xsl:text>

        <!--  <xsl:apply-templates/> OR -->
        <xsl:apply-templates select="//t:text"/>
        <!-- just use the pull paradigm on the TEI body so you don't get a meaningless TEI header dump in your document -->

        <xsl:text>\end{document}</xsl:text>
    </xsl:template>

    <xsl:template match="t:head">
        <xsl:text>\section{</xsl:text><xsl:apply-templates/><xsl:text>} </xsl:text>
    </xsl:template>

    <xsl:template match="t:p">
        <xsl:apply-templates/>
        <xsl:text>

        </xsl:text>
    </xsl:template>

    <xsl:template match="t:hi">
        <xsl:text>\emph{</xsl:text><xsl:apply-templates/><xsl:text>} </xsl:text>
    </xsl:template>

    <xsl:template match="text()">
        <xsl:analyze-string select="." regex="([&amp;])|([_])|([$])">
            <xsl:matching-substring>
                <xsl:choose>
                    <xsl:when test="regex-group(1)">
                        <xsl:text>\&amp;</xsl:text>
                    </xsl:when>
                    <xsl:when test="regex-group(2)">
                        <xsl:text>\_</xsl:text>
                    </xsl:when>
                    <xsl:when test="regex-group(3)">
                        <xsl:text>\$</xsl:text>
                    </xsl:when>
                    <xsl:otherwise/>
                </xsl:choose>
            </xsl:matching-substring>
            <xsl:non-matching-substring>
                <xsl:value-of select="." />
            </xsl:non-matching-substring>
        </xsl:analyze-string>
    </xsl:template>

</xsl:stylesheet>

 

The XSLT declaration and the LaTeX preamble

Put the following after your XML declaration. This will ensure output is LaTeX-friendly.

 

<xsl:strip-space elements="*"/> <!-- for LaTeX -->
<xsl:output method="text" encoding="UTF-8" indent="no" omit-xml-declaration="yes"/>

 

\DeclareUnicodeCharacter{2060}{\nolinebreak} was added because LaTeX complained about an undefined character in some of my students XML data. Personally, I had never gotten this error before, so you might as well leave it out.

Creating environments

As we had just learnt some XSLT basics, I wanted the students to use at least one push and one pull paradigm type template. So the task was to process any element from the TEI header using the push paradigm and then a pull paradigm template for the body. To make this little template more efficient teaching-wise, I decided to introduce how to create a LaTeX environment using XSLT for the TEI Header / push paradigm and do at least one other command using the pull paradigm on the TEI body. Also this demonstrates as opposed to for the body.

So this next piece of code sets up an itemize environment for persons present in the header. In a “real” stylesheet, it would probably be more wise to check, using whether there is one potential element like that present and only paste the \begin and \end on that condition.

Also, as you might have noticed, all the LaTeX commands are inside . This looks a bit confusing at first but really isn’t. Just make sure you don’t create invalid XSLT by shuffling them around.

 

<xsl:text>\begin{itemize}</xsl:text>
<xsl:for-each select="//persName[ancestor::t:teiHeader]">
    <xsl:text>\item </xsl:text>
    <xsl:value-of select="." />
    <xsl:text>

    </xsl:text>
</xsl:for-each>
<xsl:text>\end{itemize}</xsl:text>

 

Pull paradigming emphasis

When creating simple commands using the pull paradigm, be sure that you don’t end up with too many “overlaps” since “simple” commands in LaTeX don’t take multiple paragraphs as arguments. If in doubt, always use environment and the global switches (like \bfseries). Since you are automating things, you always have to take into account that data might not always be marked-up in a way which makes sense to you. There can easily be linebreaks inside a single italic highlight. If this is the case in you data, better create an environment. For simple purposes, however, this is good enough:

 


<xsl:template match="t:hi"><xsl:text>
\emph{</xsl:text><xsl:apply-templates/><xsl:text>} <xsl:text></xsl:template>

 

With these commands (and genereally when transforming to LaTeX), you sometimes need to make sure you don’t involuntarily add spaces or lack space which will make the output hard to read and debug.

In this example, I made sure not to add any whitespace inside the template rule and also did not have Oxygen format or indent the XML to avoid these unwanted spaces.

And finally: Escaping entities

As you might remember, markup languages tend to use entities to escape certain characters. Bad thing is, LaTeX and XML use different entities. So we need to escape them. I know that the OxGarage standard stylesheet does this using the translate() function but I prefer to use since it’s less “messy” than a nested translate() construct.

Ah, and side info by the way: There is this standard stylesheet from the TEI consortium which might be of help if you are looking for inspiration. Since it is very generic, however, it might not be helpful if you are a newbie at both XSLT and LaTeX. The XSLT is pretty advanced and also the LaTeX probably uses some commands you might not be aware of.

 

    <xsl:template match="text()">
        <xsl:analyze-string select="." regex="([&amp;])|([_])|([$])">
            <xsl:matching-substring>
                <xsl:choose>
                    <xsl:when test="regex-group(1)">
                        <xsl:text>\&amp;</xsl:text>
                    </xsl:when>
                    <xsl:when test="regex-group(2)">
                        <xsl:text>\_</xsl:text>
                    </xsl:when>
                    <xsl:when test="regex-group(3)">
                        <xsl:text>\$</xsl:text>
                    </xsl:when>
                    <xsl:otherwise/>
                </xsl:choose>
            </xsl:matching-substring>
            <xsl:non-matching-substring>
                <xsl:value-of select="." />
            </xsl:non-matching-substring>
        </xsl:analyze-string>
    </xsl:template>

 

And that’s it. I hope this was useful to you.

Cheers,

the Ninja

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

Planning your project for “service providers”

When writing my last post on how to earn money with LaTeX I realized I actually had a lot of advice on planning and scheduling your project as well. So I will sum up my experiences with all sorts of “customers” (be it project partners or whatever you have).

Motivation

This is not to complain how horrible things are but just to sum up a few things you should take into account that an unexperienced person might not find self-evident. Seeing as my days of being unexperienced myself are not very far away, the learning process is still pretty fresh and I still remember the problems a beginner can face, so I hope to be able to provide valuable advice.

Some of the advice is copied out of the earning money post, so don’t be confused if you feel like you might have already read some of this. Initially I had wanted to extend the old article but since it already was so over-long, I decided to take this out into its own post. This is also why I will start with producing print-ready PDFs for a publishing house, since this is where I had started my ramblings in the last post.

Communication between two worlds

Your job is to communicate the technical stuff in a way which makes sense to the (probably non-technical) customer. So you need to understand their language to deduce from it what it is they want. Then, you should reformulate it in a way which is a bit more technical and “re-translate” it to them to check if you got it right. This is a necessary part because mostly, the requirements you get are not specific enough and there are a lot of decisions to be made in the process of planning implementation and acutally implementing these requirements.

Production paradigms and methodologies

In the past, people used the so-called “waterfall model” which means that they would get the requirements once from the customer and then implement them like this, working around any lack of information they might encounter. Modern methodologies lean towards shorter producation cycles where you produce a “minimal working example” fast so you can check whether this is actually what the customers want. If there are any additional decisions to be made or information missing, you re-check with the customers straightaway. You try to avoid implementing unnecessary features you think are cool but the customer didn’t ask for. For now, I will leave it with this super short info on methodologies. Maybe I will follow up here with a post of its own at some point in the future.

Pitfalls in organizing your work. On the example of producing print-ready output

Only because you know some LaTeX doesn’t necessarily mean you will know how to cater to the needs of a publishing house. Try to get the opportunity of working with them for free. Again, small publishing houses or university publishers often offer the option that you hand in the final PDF which comes a lot cheaper than having them typeset it for you. This will save the scientist in question a lot of money (500-2000€ depending on the amount of work). Offer to some university professor that you will typeset their book for free, so you will have done the interaction with the publisher at least once, have a credential to show and know what publishers want. Also, don’t underestimate how long it might take. There is a reason a job like this can pay up to 2000€. Especially scientific publications often have a million changes and corrections before they are finally ready for print.

During the process, you might realize that producing a PDF which corresponds exactly to the publisher’s criteria is more difficult than you would think. At least, that was what it was for me. I had used LaTeX and knew how to do the customizing needed to make my thesis advisors happy, but the publisher ended up wanting a million things changed I had never even dreamt of doing in LaTeX. Advisors will quickly be happy with nicely typeset output and correct citations. Publishers, however, want a very specific look. For example, the first thing I had to change is the typesetting of the footnotes which no advisor of mine had ever cared about. I had never customized footnotes before and wasn’t even aware that could be an issue. So if you haven’t done any of those things, I suggest you start reading up on them now. (An upcoming post on LaTeX for the Accidental Editor will explain all those things).

It will probably be a lot more work than you might have expected and the work might also be pretty different than what you are used to doing with LaTeX. Anticipate this (!). Publishing houses also tend to find typographical problems you hadn’t even dreamt about beforehand.

Scheduling the work

Apart from traditional publishers, I have found any customer really is like this. The version of text etc. you are handed is never the final one. You typeset it and think you’re done and only then they notice the millions of typos and so on. The first “final version” together with the preparatory and consultation meetings is half of the work / hours you need to plan for (believe me!). If have found that usually, the corrections are at least as much work as creating this “first final version” even when I had to create the whole layout and some TikZ for that first version”. Correction work after this is done will seem to expand exponentially! This is not necessarily a horrible thing if you know about it an plan accordingly. If you think like a beginner often does, however,  and don’t feel confident enough dictating your terms and communicating your needs, they won’t be met. You are likely to find yourself in a hot mess. This is great relationship advice too, by the way 😉

The first “final document” they hand you is actually the first draft

This is super annoying and I’m still thinking about how I can prevent this from happening (again) because often, it’s just due to a lack of diligence on their part. But of course, once their document is typeset in LaTeX, you are the only one who still knows how to make changes. Anticipate this and also, probably (secretly) include at least 10 hours more than you need in the fee / estimate of hours needed for corrections (even for teensy mini-projects and probably especially those as people tend to be even more careless with them). There will be many corrections to make. Should you find a way of preventing this from happening, please inform me 😉  So far I have not been very successful. People only see the typos or visual problems in the final fully typeset version. But these extra corrections you are not getting paid extra for are often what turns a profitable side job into one that’s not profitable anymore. Also, these corrections mostly need to be made instantly or last minute. So inquire about when the deadline is and make sure you are available at that time. Probably best plan to be with them at that time (the last hours before submission) and charge them for it preventively. Because you will end up having to do it anyway. Also, the more scientific the content, the more stressful it’s probably going to be.

Creating a ‘safe space’ for your work by saying “No” – Learn to be strict with your customer

Never forget that you are the last part in the food chain. Your customers will hand in the data late, like 2 hours before the deadline and you will be the one whose head is on the line, unless you set up your conditions very clearly before. If you don’t want this side job to become stressful, you need to make the schedule for them. They have no clue how long their own corrections and “completely unforeseeable” addtions will take.

Give them a deadline long before your head is on the line. Imagine you get a LaTeX error in the last minute and don’t know how to solve it. Also, to prevent this, create a minimal working example before you receive the final data (this will be in the last minute and way too late to start). Ask for a mandatory “minimal working example” and implement this right after the first meeting, so they can give feedback. They will probably want  litterally everything changed. Or, even worse, they say it’s perfect and thanks a lot. The most important thing to know is: They will akways have a millon corrections and the correction process will take at least as long as creating the “first final version”. Even if they tell you “it’s perfect, thanks so much” rightaway. Corrections will come. I have not had a single project where this was not the case. If you have other experiences, please let me know. But also from my colleagues I hear nothing else.

You need to know this and never let anything cheat you into believing otherwise. The less corrections or feedback you get after the first draft, exponentially more will come the closer you reach the “real” deadline of the project (by this I mean closing in to the actual end, after the “first final version”).

Helping the customer find out what they really want

Often customers will end up realizing that they don’t like their own idea anymore once it’s implemented. Or they might not have an idea of their own and you need to make multiple mockups until they’re happy. But the customer not having an idea of their own should never be mistaken for them happily accepting whatever result you produce. Once you have come up with an idea, they will probably tear it apart. This is not meant in an unfriendly way, but it’s just a fact that after you serve them a concrete implementation they will suddenly realize exactly what they would have wanted. Hint: It’s probably the exact opposite of what you just laboriously produced.

Protect yourself by insisting that extra features are all super difficult to implement (charge extra)

I don’t say this to discourage you but just to give a realistic idea of how it’s going to go. This is the same for any kind of work where you produce a technical implementation for a “customer” who will hand you the data to be represented. This can be an XML-based project in the Digital Humanities or a LaTeX-based poster printable. Also, another tip from the DH world: Always say everything is incredibly hard and takes super long and you are not sure if it can be done at all if people ask for extra stuff which wasn’t part of the contract before. I used to hate this and think it was a sign of  “bad service” or laziness but it’s really just a necessary precaution. You need to protect your own time or else you will end up working for free. If necessary, charge extra. This also means that you need to write down a very clear “contract” of what you agreed to do for which money. Don’t add extra goodies for no extra pay. Once you ask additional money, the feature probably isn’t all that important anymore.

Always make a first draft with (at least snippets of) real data straightaway

Be sure to make the “mockup” using their “real data”, not lorem ipsum only, if possible. Their data might not look anything like lorem ipsum. Do it right after the first meeting, so you did your part. If they fuck it up and don’t hand you any data before the deadline, this proves that you did your work and they will not be able to back out of paying you.

Some security is never a bad idea. Also, this makes sure that you get “most” of the work (maybe the first third) done early. Remember, if you are somebody who is always Mr. Last Minute, this job probably isn’t for you. The customers will likely hand you the data way too late. If you wait with the first mockup until after they give you the final data, you are never going to make it since they will want to give feedback and have changes made as well.

Specificities of the Humanities

In the Humanities, it is most imporant that you learn all the features MS Word offers and how to reproduce a Word-like-but-better look. If they are to let you use LaTeX, you first have to prove it has all the features they are used to from MS Word.

Like I complain about in my quitting word post, everything revolves around MS Word in the Humanities. This means that even if you choose not to use Word in your own private life, you will have to know how to work with it. Most importantly, how to make the best of it by extracting the data to further process it using a different data format.

Closing thoughts

So, these are some general thoughts on working as a “service provider”. The experiences are both from some contract or freelance work with LaTeX and project work in the DH. At some point, I will probably write a post specifically on DH project management as well. But for now, I just want to stress again that this post is not to bitch about anybody or to scare anybody away. I just wanted to share some of my experiences which could be useful for someone looking to get started, so they might have an idea of a few things to take into account.

So long and thanks for the fish!

The Ninja

 

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00