Hacker News new | past | comments | ask | show | jobs | submit login
Show HN: LaTeX Boilerplates – Plain-Text Document Production System (mrzool.cc)
104 points by mrzool on Dec 2, 2015 | hide | past | web | favorite | 43 comments

I use a similar workflow using Pandoc at work. I painstakingly re-created our corporate Word documentation templates using LaTeX and then set up Pandoc to generate documents from Markdown using these templates.

In addition to this, I used Haskell and Diagrams to produce DSLs for rendering various UML documents from text based descriptions. These can be rendered in both vector graphics formats (SVG and Encapsulated Postscript) as well as a written description of the diagram that can be provided for accessibility reasons.

The big take-away I got out of this process was that I could write human-readable documents that were also machine-readable while also providing a higher level of accessibility for this documentation than would be possible using traditional WYSIWYG tools.

I highly recommend this style of documentation workflow.

I found LaTeX to be an enjoyable way to create non-traditional PDFs with better control over styling than you would get from something that rendered HTML to PDF directly, like Prince or WebkitToPdf. The downside was all the Googling and troubleshooting when things didn't behave as expected -- LaTeX is pretty much the opposite of WYSIWYG and doesn't have Chrome Developer Tools ;-)

In my case, I was actually stuck with creating a template for Invoice/Order PDFs based on a CRM that was written in PHP, so I made a PHP script that output LaTeX, then rendered that in a folder. The trick was to use a temporary folder for each document render, and to manage the process hands-free using latex-mk: http://tex.stackexchange.com/questions/210500/why-is-somethi...

The resulting PDFs then didn't break lines in the wrong places, had the correct margins on the first page vs other pages, were very graphically rich with vector graphics, and could be produced quickly on demand through their web-based CRM, all thanks to LaTeX and a few days' time debugging.

Is your Haskell -> tex -> SVG/EPS open source by any chance?

I'd love to both study the .hs (to further my learning), but I also have a need to make some documents.

It is my goal to open source the tool at some point in the near future. I have a few IP related things to work out with my employer first, as a courtesy.

ShareLaTeX also maintain a pretty handy database of LaTeX Templates/Boilerplates: https://www.sharelatex.com/templates

Yes but the difference here is that you write in markdown, and it does the TeX-ing for you.

Oh! I had entirely missed that.

Using templates with low-level formatting commands defeats the point in LaTeX being about high-level semantic macros. Why not define an \author macro? The YAML input and the input using a well-crafted set of macros would be very similar, to the point where I feel like the OP is really misunderstanding what LaTeX is about.

I think for the invoice YAML makes sense. I would rather use an existing YAML library to generate invoice input files for the pandoc template than generating latex source files directly while sanitizing input for latex special characters.

I think what parent comment was getting at is that you shouldn't be generating LaTeX in the first place. Instead use LaTeX macros to pull the data from the source files. Probably easier said than done.

We've been taking a similar approach at overleaf[1], where our rich text mode let's non-LaTeX users write papers without needing to code.

We've also had success in working with publishers to simplify the submission process for research articles, with direct one-click submission links where we pass the files plus meta data.

See e.g. https://www.overleaf.com/blog/269 for a recent example.

[1] https://www.overleaf.com

At the time of writing my article cited above, I didn’t yet came across this one:

[Sustainable Authorship in Plain Text using Pandoc and Markdown](http://programminghistorian.org/lessons/sustainable-authorsh...)

Thanks for sharing. "Awesome-CV" looks particularly interesting.

I sometimes wonder why nobody ever attaches real world success data for different styles of resumes. Like most(?) people, my resume has also undergone an evolution in style and layout. I would gladly trade whatever I find aesthetically pleasing about mine, if that meant a greater success rate in having my resume read/chosen.

I don't think that kind of data would be useful. It's kind of like asking "what do I have to do to make my song a #1 hit?" It depends entirely on what the mood is of the people who happen to be looking at your resume, and the culture that guides the judgements they make about it.

I had spent a good deal of effort building a very simple and pleasing resume using LaTeX, and I ended up having a professional career counselor look at it, and she said "Did you use a template? It looks too much like a template." So what? Templates are templates because they look good. If it didn't look like a template, it wouldn't look professional. And something that should've elicited a complement was instead peddled as disappointment.

Instead, I'll just figure that I wouldn't want to work for anybody that trusts people who are too petty or too clueless to make good hiring decisions.

>It's kind of like asking "what do I have to do to make my song a #1 hit?"

Sure, but it's also kind of like asking - Given the fact that all these songs are number one, could we extract some common features?

Maybe you'll find out that songs have to be shorter than 3 minutes or nobody plays them on the radio, or that they have to be dynamically compressed within a certain frequency range because most people listen to music on hardware that does not reproduce certain frequencies very well, or that having a weird time signature makes a song unpopular, etc.

>I wouldn't want to work for anybody that trusts people who are too petty or too clueless to make good hiring decisions.

Hah, that would exclude a large portion of the professional software industry !

My point is that those features are transient. A #1 song today probably can't be #1 in ten years. If Beethoven were born today, he would not be topping pop charts, even if you have plenty of data showing that his style of music is good. Resume writing either comes down to presenting the fact that you are clearly the most qualified for the position, or because you caught the fad of resume attention-grabbing design in the right way. The later will only really help you if you're competing against many similarly-qualified yet boring candidates. It's better to have more valuable content on your resume than to apply statistics to its paint job.

>Hah, that would exclude a large portion of the professional software industry !

It probably does, but I don't actually want to work for a large portion of the professional software industry. I want to work for people that value me and share my vision. And in turn, I want companies that make those kinds of hiring decisions to not have access to people like me.

Okay, well this seems to be a new point you're making. I think we all realize that you can't have features that are eternal/absolute.

Your example doesn't carry your point. Beethoven, like Mozart actually is popular simply because both are part of mass culture. Classical music however is not part of popular culture and is restricted to certain niches.

Also, there is a legimitate view out there that pop music hasn't changed for the past few decades, and has certain recurring themes - love, loss, sex, etc. But anyway, that is not a very interesting conversation.

I don't agree with your view on resumes. In my opinion, resume writing comes down to knowing the mind of the person who is going to read the resume and convincing them that you're the right candidate. Since mind reading is usually a difficult task, all one can do is increase the probability of success by adopting tips and tricks that others have used.

> It's better to have more valuable content on your resume than to apply statistics to its paint job.

By writing a resume the "common" way, it does not diminish your own value and self-worth. It seems like you want companies to appreciate you only if they hire someone in HR who also appreciates your style of writing resumes. Thats pretty bizzare TBH, but hey whatever works for you.

It's not a new point, it was the first thing I said. Beyond the basics (correctness, accuracy, ease-of-use) what people want in a resume is a fad. What people like in music is just as much a fad.

You can't read a person's mind, but you can change it. That's what your resume is for. You don't have to read any minds, you have to get others to read yours.

>It seems like you want companies to appreciate you only if they hire someone in HR who also appreciates your style of writing resumes.

If a company hires HR people who think "simple and professional" is not good enough for a resume, then they almost certainly won't appreciate me. Simple and professional is what I'm offering. I'm not going to jump through flaming hoops and read resume acceptance statistics to get noticed. I'm going to solve actual problems.

Kudos for this great, yet simple and lean toolchain!

Anyone familiar with command line tools and a corresponding aversion for bloated WYSIWYG apps will second the underlying idea that MS Word (and the likes) “should die” in favor of plain text workflows.

Yet, with the help of Pandoc (which does the heavy lifting in these boilerplates), nothing prevents you to keep using Word as a front-end and plug it in this exact same workflow. Word may not be the best-of-bread typesetting engine or layouting tool, but to many it still is useful as a quite decent word processor.

For those interested, I did a (long-read) write-up on how one could go from Word over Markdown to even InDesign (as an alternative templating/typesetting engine, instead of LaTeX/XeTeX): http://rhythmus.be/md2indd/

Thanks for all the feedback!

Make sure to check out this article where I talk in depth about a typical workflow and the rationale behind this project:


One thing I didn't really see in that post is why not just LaTeX directly. Is it just that you prefer Markdown syntax? (Which I guess is a valid reason.)

LaTeX is complicated and verbose. Markdown and YAML are terse and readable.

Also, separation of form from content makes life amazingly simple.

I agree that separation of form from content makes life amazingly simple, that's one the main virtues of LaTeX. :)

As I said before, preferring Markdown and YAML solely on account of syntax seems fair to me.

If both content and form live in the same file, like in the standard LaTeX approach, they're not separated.

My approach is to abstract all style-related concerns in a template and keep the content in dedicated files: YAML for structured content (CVs and invoices) and markdown for prose-like content (letters).

Beside making life easier by using formats more suited, syntax-wise, for the particular type of content I'm dealing with, this opens up new possibilities for automation (e.g. I can iterate on repetitive data structures, for example for building an invoice table) and ultimately results in DRYer LaTeX code in the template.

I thought "the standard LaTeX approach" is that you put all of the style information into a document class (or, if you have only minor modifications of a standard document class, into a package) and then all of the content in a separate file with extension .tex. I not only thought that was the standard LaTeX approach but also that that was the point of LaTeX: your document markup is semantic and all formatting issues are decided elsewhere so you can change them independently of the content.

(And whether or not that is the standard LaTeX approach it is certainly a possible and recommended approach in LaTeX.)

In your approach you don't just separate style from content, but additionally distinguish two types of content (the type you'd write in YAML files from the type you'd write in Markdown). That is different from LaTeX, where both the YAMLly and prose-like things are put in LaTeX source files (for the YAMLly stuff you define macros, like \author, \title, \signature, etc.).

At any rate, as I said before: preferring YAML and Markdown to LaTeX syntax seems to me a valid reason for doing things your way. I just wanted to point out that LaTeX makes it easy to separate form and content, too.

I just use a Makefile[1] for this, I just type 'make', and it builds it and uses xdg-open to open it in my PDF viewer. Much faster than waiting for ShareLaTeX or similar web apps to re-render.

Gummi[2] is also nice for instant feedback, and you don't need to get the whole toolchain working by hand.

1: https://gist.github.com/rhinoceraptor/8b7e9bf650db6396e27e

2: https://github.com/alexandervdm/gummi

You can try latexmk, it does almost all of the work when building LaTeX (including getting cross-references right) and can even watch for changes and rebuild the document when necessary, updating your PDF reader too. Just calling _latexmk -pdf -silent -xelatex -pvc mydoc.tex_ should suffice (the -pvc option is for the continuous build and preview mode).

I couldn't get it to work on Windows previously.. is it any better now? :O

evince reload the pdf when I recompile it. So you might be able to get rid of the xdg-open call.

RStudio (IDE for R) has a great MarkDown to PDF, Word or HTML using Pandoc. http://rmarkdown.rstudio.com/pdf_document_format.html

Might help you to see their process. You can do the whole thing with CLI but easy in their IDE.

Why would you want to use an IDE (RStudio or whatever) to run pandoc over an markdown file?

You don't have to. That is why I said it can be run in command line, just easy to hit the one button.

They did some good coding for Pandoc is my main point.

Man, that example CV is beautifully simple. It's so weird to see a CV that's not peppered with acronyms.

It sounds like a good idea, until you need to write advanced mathematical documents, in which case it all breaks down.

Any tips to make a latex pandoc workflow viable for advanced math documents with custom commands and such. I.e. using the mathtools package and various advanced latex math commands?

They look great. Installing pandoc is a pain, though. My CV is LaTeX as well—using the moderncv template—and I build it regularly on both GNU/Linux and Mac OS X:


> Installing pandoc is a pain, though.

I'm genuinely curious about this statement. I thought you must be using Windows, but the latter part of your comment contradicts that.

Is there a good CSS for good looking print-ready html letters, resume, ... etc?

It would be nice if the website had the corrospinding markdown for comparison.

Oh, needs Make. Probably not easy on Windows..

Applications are open for YC Summer 2019

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact