10

I have been using Latex (with TexStudio) for some time to keep a research notebook and made some observations:

  • After the overall style of a document has more or less settled, one wants to worry about formatting as little as possible. All the Latex markup for even simple tasks (like including an image) becomes tedious.
  • Liberal use of \newcommand helps facilitate repetitive tasks, but due to difficulties of Latex syntax (like lack of named arguments and abstruse compiler errors), it's not always straightforward. Also, sometimes updating old \newcommands requires going back and changing every instance of previous usage.
  • Rearranging parts of the notebook (as some sections sprawl more than expected or the logical structure of the project evolves) sometimes takes a bit of finesse.

It is often said that Latex separates style from content. It certainly does a much better job of this than alternatives like Word, but it doesn't, really - for example, if I have some information that needs to be presented as a table, I end up having the information interwoven with low-level markup for table structure.

I got the idea that I could decide on some kind of pure-data format, perhaps with minimal semantic tags (for instance, to indicate species names so they can later be italicized), to record only my research progress. I could then write a script (eg. in Python) to generate Latex source for a report on this. In theory, this would be analogous to how CoffeeScript is compiled into JavaScript. It would also introduce an extra layer of separation between recorded research (which I would like to write once, and never modify) and stylistic changes (moving sections around, renaming a chapter, changing the formatting of tables).

Are there any major problems with this idea? Has this already been done? Am I massively underestimating how much work it would be?

  • 2
    Markdown? Pandoc? – cfr Mar 30 '15 at 22:35
  • If the input is regular and the overall needs on the output side are not complex, then Markdown or org-mode are a good way to go. It is, however, a fairly inflexible transformation process and you almost entirely lose semantic markup (but see gpp for some help there). If the input is unusual (e.g., tables with complex multirow and multicolumn stuff), and if you want superior output, then I think you need to intervene at the *TeX level. (Generic *TeX output is only 'superior' when compared with generic word processor output.) – jon Mar 31 '15 at 5:41
  • ... for table input, consider using something like datatool or csvsimple with your data in a .csv (again, though, this leads to an inflexible importation into the .tex file). On the \newcommand problem (which I've certainly experienced many times) it's often, though not always, a symptom of "bad" design planning -- i.e., of not spending enough time thinking before macro-writing. Simple example: if you have \macro[1]{2}{3} and are changing it to \macro[1]{2}{3}{4}, you'(we)re probably better off using a key-value system the first time around. – jon Mar 31 '15 at 5:43
6

You might want to take a look at Pandoc, which describes itself as the "swiss-army knife" of document conversion. With Pandoc, you're able to create documents in various languages, most notable ones with Markdown-style syntax and are able to easily create LaTeX documents from them.

It also supports a heap of customization options which should allow you to suit it to your specific task and I presume it's way easier doing it this way than writing up a new solution from the ground up; you'd end up trying to reinvent the wheel.

Try taking a look at the README and the scripting guide provided on the official web page for more information.

  • Concur, while I have not used it several of my computer science advisees found it very effective during their capstone projects. – R. Schumacher Mar 30 '15 at 22:38
  • This is exactly the sort of thing I'm looking for. I'll leave the question open for a while in case someone has an interesting alternative to Pandoc/Markdown (since I don't know if there are any). Thanks! – Superbest Mar 30 '15 at 22:40
5

Many people use XML for this, there are several XML vocabularies, perhaps docbook or TEI being best known. the MathML spec for example is all encoded in "xmlspec" XML markup and html, xhtml and pdf versions of the document produced, the pdf version going by way of LaTeX, see the alternative versions linked from

http://www.w3.org/Math/draft-spec/mathml.html

TEI (about which I don't know that much) maintain extensive stylesheets going to LaTeX as part of the general processing suite

http://www.tei-c.org/release/doc/tei-xsl/#intro

Docbook have stylesheets onverting to latex as well

http://dblatex.sourceforge.net/

5

There is (and imho always will be) a conflict regarding the wishes for "minimal semantic tags", "simple, straightforward syntax" (in languages like LaTeX) or "intuitive menus and dialogs" (in GUI textsystems) and highly sophisticated output.

Markdown e.g. is in its core easy to use and learn - but you can't create a complicated table with it, or fine tune the format of citations or lists. And so you can find on the internet quite some discussions how to extend the language with e.g. css-styles or new syntax tags, or how to inject latex code when using pandoc.

Styling an output can be an art. A lot of the low level code e.g. is there to create a beautiful table or fine tune the page breaking or a list. So before switching to some automated system you should ask yourself how much of the code tweaking you did was due to manual corrections and changes to get a more pleasing look.

  • This is all true but in the context of the research notebook application in the question there should be a lot less tweaking. Tables are the issue even though they only need to be readable. I'll hazard a guess here and suggest that for keeping research notes a table can be structured as a simple m*n array with no merging of cells. To be able to paste CSV data (for example) and have it render may need some customisation but nothing too complex. – Chris H Mar 31 '15 at 14:43
3

You could also try emacs with org mode. It has a markdown-like syntax and can be exported to latex, HTML and others.

3

A late reply...

I used latex as my writing base for a few years but I was unhappy that Latex is somehow the end of line and conversion to other formats (most notably HTML) was really tedious and problematic (such as Tex4ht). At the same time I noticed that my writings can get away from being purely semantic (if I do not keep the right discipline constantly) and death of some packages can break my entire document. It is not also easy in Latex to add several different formatting to the same piece of content (compare these limitations to the ease and robustness of the concept of style classes in HTML/CSS). So I turned to find alternatives that are text-based, human readable and also easily convertible to other formats.

Result of my investigation on markdown-like writing styles was that only Asciidoc has the extendability features I needed to make sure I can style my final Latex (PDF) or HTML exactly the way I want.

I used Asciidoc (actually Asciidoctor) to write a full academic book and then convert it automatically through the following routes:

Asciidoc -> Docbook -> Latex -> PDF

Asciidoc -> HTML

Asciidoc -> HTML -> Docx

You can find the final PDF result here: http://www.diva-portal.org/smash/get/diva2:866706/FULLTEXT03.pdf

Most of the job is done by Asciidoctor, but I had to write a small-tool chain around it to automate different conversions. I put the tool chain code (which is mostly a make file plus some xslt) here https://github.com/shahryareiv/asciimint which of course needs to be cleaned and described later when I find a time.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.