Regarding comments and contact info

Dear all,

apparently the LaTeX Noob is not alone to be a noob 😉

I just realized I had to approve your comments before they are published. Oops 😉 Will see to that more quickly in the future.

Also, I heard that some of you were not able to find contact information which maybe I might have messed up too 😉 I guess I just hadn’t really thought about having actual readers who want to contact me so far. And I am very happy that you exist and do wish to contact me! I will therefore add my contact info in the about section. Sorry, I am such a complete idiot not to have thought about this before 😉

Best and thanks again for all your positive feedback!

Advertisements

[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