A meta-language for LaTeX

Whenever I write TeX/LaTeX documents, I always find that annoying because I can't really focus on the content, It's not that I don't like TeX or what it does for me, it's just the fact that the document quickly becomes something way too verbose.

I was thinking about adopting an intermediate syntax, something more "dry", that can help me focusing on the content and only use LaTeX later on in the process to create the last pieces of the layout and the paging.

So far I was able to identify rst ( reStructuredText ) and docbook, needless to say I have no experience with neither of the two, but I have a few requirements while asking for your help:

• support for math formulas
• support for include external resources like snippets of code or images (vector images for the most part)

The kind of documents that I would like to write while adopting this "dry" solution are small books and articles for the most part, so often times I need to separate things into chapters or paragraphs and I would like to have a solution that is modular and flexible.

-
How is docbook better than latex in terms of being verbose? Essentially, in latex you have in line macros \something{...} and environments \begin{something} ... \end{something}. Define semantic macros and environments, and then you can focus only on the content. –  Aditya Jan 6 '14 at 18:44
@Aditya I'm not expressing a preference in my post, I just found this 2 language as potential replacements, I still think that rst wins in terms of "compactness", there are also "extensions" for rst-like syntax like in sphinx, but I would like a comment from the users. –  user2485710 Jan 6 '14 at 18:48
I think the answer will depend on how complicated your document will be. Writing (say) a simple novel would be simple: use something like markdown. An article with a sufficiently complex mix of one or more of the following elements -- footnotes, diagrams, equations, indices, etc. -- becomes difficult with anything less than full TeX, LaTeX, or ConTeXt. And never underestimate the value of thinking about what you will need to write before writing it: don't just start coding a complex table, but think about (maybe sketch out) how the disparate information should finally be presented. –  jon Jan 7 '14 at 3:34
I'm lost on what you call metalanguage in the title. :( –  Paulo Cereda Jan 7 '14 at 9:08
@user2485710: I actually know what metalanguage is. :) The question is how you want to apply transformation rules. This sounds to me more like an intermediate code written using an arbitrary grammar for representing a subset of TeX. –  Paulo Cereda Jan 7 '14 at 11:37

I can suggest Pandoc-markdown with Pandoc.

Pandoc-markdown is a markdown format (there's nothing easier or more compact out of it) with a list of extensions, among them there are tables, TeX-math, raw TeX and so on.

With Pandoc you can convert your markdown document in LaTeX or directly in PDF, and control the conversion with a simple system based on command-line parameters.

Moreover you can obtain a good fine-grain control over conversion with a simple system of templates.

I'm not a computer guru and I can say that I've written my own LaTeX template for Pandoc thirty minutes after reading the Pandoc documentation, and I'm writing a series of technical documents in Pandoc-markdown.

It's worth giving a glance.

-
it sounds almost identical to rst from docutils: what is the difference ? –  user2485710 Jan 7 '14 at 11:26
@user2485710 As far as I know rst is aimed to document Python code. The phylosophy of markdown is the "easy-writability" (if I can say so) and the "easy-readability" of documents. Moreover, Pandoc-markdown is designed for multiple output formats. In other words you can get a lot of expressiveness with ease of writing. –  Jean Baldraque Jan 7 '14 at 11:35
Ok , what is the utility that I can use to produce latex from markdown ? I can easily translate markdown to Html but I can't really find a name for a latex-related tool –  user2485710 Jan 7 '14 at 11:50
nevermind, I found out that you can use pandoc -o file.tex file.md –  user2485710 Jan 7 '14 at 11:55
@user2485710 Markdown is far less powerful, but there’s dozens of complete parsers (or to-HTML converters) for it. Coming from reST you’re going to spend a lot of time finding decent plugins to compensate for lack of features in the base version. Also, there are mutually incompatible dialects (reddit != github != stackexchange). reST on the other hand has one huge monolithic spec that is easily extensible via directives. The drawback is that it has only one complete implementation (Docutils), and most other converters just don’t cut it, and btw. their rst2latex converter is incomplete too. –  phg Jan 7 '14 at 12:37

The problem with reStructuredText, SDF (Simple Document Parser) or similar tools, that allow work with a simple markdown text that can be exported to LaTeX, is that soon or later you are limited to a basic format (list, quotes, sections, verbatim text ...). If this is all you need, perfect, otherwise is a nightmare.

Suppose that you have a reStructuredText that generated a LaTeX file that is not 100% perfect, and you must edit it to obtain the final format. After that, you want update your document. Now what? Modify the source mean lost the efforts put in the LaTeX file. Edit the LaTeX to preserve these changes means that the source file become obsolete...

So, for complex LaTeX documents that must be updated, my suggestions is to work directly in LaTeX, but in order to not be distracted by the LaTeX commands, follow these suggestions:

• Write the entire document in plain text and only when completed, make it a LaTeX document. Only then be worried about the look and feel (figures, cross references, orphan lines, spacing, etc.)

• Format cleanly the source.

 Some text

\section{Title}

This is a text


is exactly the same for the LaTeX compiler that:

Some text \section{Title} This is a text

but in this way is obviously less readable by humans.

In parts like tables, simply adding some spaces to align the columns improve a lot the readability, what is important also to detect code mistakes (a lost &, for example). A simple indentation improve a lot the nested list, etc.

• Make it simple. Maintain your style format as close as possible defaults of the class and essential packages.

Consider some like:

\section{Title} (No doubt. Here start a section named "Title")

versus

\section{\sffamily\textcolor{blue!60!black}{\textbf{\Large Title}}} (What the hell means this line?)

The first is better not only because you will see only the structure command, that is more informative that intrusive. Probably the default is also more elegant that your choice. If you really need a different "look" for you section titles, consider change the class (from article to paper, for example) or the proper command of the class for change the defaults or some package todo this like titlesec, so all your modifications are a few lines in the preamble, no tons of ilegible code between the text.

• Use macros to simplify the formatting code. Maintain all the complicated commands sequences in the preamble. For example, if you want highlight some words in this exotic way:

\textcolor{blue!60!black}{\textbf{\emph{{word}}}}

then is better make the macro \myhl in the preamble:

\newcommand\myhl[1]{\textcolor{blue!60!black}{\textbf{\emph{{#1}}}}}

And so you only need to write \myhl{word} in the text.

• Use often \input or \include. For thesis and books is a usual practice maintain each chapter in separate files and mix with \include{file}. However, a chapter or even a simple article with several floats of tables and figures between paragraphs is still hard to edit. But you can put these floats in separate files and include with \input{file}. With well-choosen names, this command is also more informative that intrusive. Even you can make also this with the whole preamble. And with any chunk of plain text that you do not want to see mixed with LaTeX commands while editing it. Not only the main file and subfiles are more readable in this way. Also is safer, as you cannot edit accidentally the parts where you are not working on. And find some parts to edit is easier also.

• Among the more annoying usual LaTeX commands for humans beings are list environments. A well-formatted simple list is easy to read, but nested list with several levels is hard to follow without a PDF preview. Fortunately, you can Simplify itemize commands typesetting without using a markdown language outside LaTeX.

• Finally, if even the most common and simple structure commands are disturbing you, use the free and gratis editor LyX that is WYSIWYM (what you see is what you mean). Here you are not limited as using a markdown language, since where LyX end, you can add LaTeX commands in ERT (evil red text) boxes, and that boxes can be closed at any time if they are very distracting. Another option could be the WYSIWYG editor BaKoMa (not free nor gratis).

-
The best WYSIWYM for latex is scientific word. The easiest to use. I tired Lyx and BaKoMa, nothing compare to the ease of using SW in terms of editing equations on the screen, copy/paste part of equations, etc... it feels like writing on paper. I do all my HW using SW. If I had to write it all in Latex myself, it will take me 1 year to finish just one HW. SW->Tex, then use texlive to compile, and tex4ht to make HTML. –  Nasser Jan 6 '14 at 22:34
@Nasser, don't forget scientific word comes with a hefty price-tag. If you actually will take the time to define a style for your works, it saves you time later. I do 2–3 assignments per week with straight LaTeX, and I'm far more confused by abstract algebra than formatting. –  Sean Allred Jan 6 '14 at 23:44
@SeanAllred, I am student, so I bought the student edition. It is only $160 for SW mackichan.com/products/pricing.html#SWPricing but for me, as student, it saved me thousands of hours in time for such tiny amount of money. I'd rather concentrate on the math itself, by seeing it on the screen as I would on paper, rather than concentrate on Latex syntax. I actually do not use paper and pencil much any more to solve something. I just write it on the screen and make all my edits on the screen, since is much easier than on paper (less chance of making an error using copy/paste) – Nasser Jan 6 '14 at 23:48 @Nasser to each his own, but$160 is not a tiny amount of money to this student. ;) Whiteboards (or a dedicated CAS if it calls for it) are your friend for concentrating on the math. –  Sean Allred Jan 6 '14 at 23:51
@Nasser Sorry, but my experiences with SW have always been bad; it writes out horrible and unmaintainable LaTeX code, but, worst of all, it relies on a several year old LaTeX distribution, which makes impossible to update the obsolete package versions it contains. Say you want to update hyperref: you'll need many other packages that have been added in the last few years. –  egreg Jan 7 '14 at 11:55

Maybe

are what you're looking for.

-
I use vim ... –  user2485710 Jan 6 '14 at 19:00
@user2485710 No problem, pandoc is a universal converter. Edit markdown files with vim, then convert to latex or whatever you need. –  Alex Jan 6 '14 at 19:05
we are loosing the focus of the question here, my problem is how to keep my doc short, not finding a tool to perform conversions . –  user2485710 Jan 6 '14 at 19:06
@user2485710 Don't know anything shorter than markdown. –  Alex Jan 6 '14 at 19:11
Just a note to @Aradnix, Word can introduce artifacts that can be hard to remove from your document. Better to use RTF or something similar if you roll that way. –  Sean Allred Jan 6 '14 at 23:47

LyX

Simply use LyX. Just write down your content. When done, either polish with LyX, or export your file to LateX, works very well.

Really, LyX was made for people like you. It even can export to epub, and as far as I remember, to HTML as well (answering to a comment of OP). Maybe you wait some days, until version 2.07 will be published.

-
markdown can be easily exported to other 1-2 interesting file formats like epub and html ... I know that an IDE will probably be a good fix but it will create a latex-only doc. –  user2485710 Jan 7 '14 at 17:02

You could use the Interpreter package to simplify the input syntax to your liking. The package requires LuaLaTeX but will allow you to easily define efficient syntax for things like \section or \textbf etc.

Formatting of math can be left in conventional TeX syntax.

-
The author of this package has some real interesting ones (like this), which I've always wanted to try (also librarian and navigator), and yet I never seem to get around to it.... –  jon Jan 8 '14 at 4:39

There is AsciiDoc which is similar to reStructuredText and seems to be getting popular recently.

But in my opinion it's easier to focus on the content when using a graphical interface at first. I'm a founder at memobuild, a browser-based editor for large documents (you can email me if you want to try); and there is also LyX.

If you want to stick with pure LaTeX, maybe it would help to setup a workspace where you have the LaTeX source on the left and the compiled output on the right, possibly with auto-compilation on save etc... That way you can read mainly from the typeset output.

-