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).
docbook
better thanlatex
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.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.:(
:)
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.