Would favor TeX readability over advanced customizations

Feb 10, 2015 at 1:38 AM
Others here might disagree, but after working with Madoko's generated TeX files for a few hours, I would suggest moving away from using custom TeX environments as these produce TeX files that are hard to read and tweak (and slower to compile).

The HTML implementation is really good, but when it comes to using LaTeX classes to produce print-ready PDF, I would suggest sticking to the simplest TeX constructs as required by most journals. These would make the generated TeX files easier to share with others as well. LaTeX's classes are built so authors can focus on content, and not try to change font sizes, colors, flow, or layout.

In my experience the only thing that requires customization in TeX documents is front matter and the placement of floats and the width and rotation of tables (maybe font sizes in tables as well). I don't think I'd want to manually tweak anything else (others might have a different experience).

That's to say I would favor having the option to not use any custom TeX environment (or maybe a simplified madako.sty).
Feb 10, 2015 at 4:08 AM
Hi Mel,

Thanks for your thoughtful post. Hmm, this is a complex issue. I think part of the trouble is that I have not documented the style of the output TeX very well. It is set up in such a way that all the 'custom' environments actually all refer directly to the standard LaTeX commands. This way, it is indeed the case that when you import a standard class file from a publisher for an article for example, you get the style of the publisher by default. However, when you add styling in your Madoko file, say, color=blue than that styling will be applied in the TeX file too.

I agree that it leads to a less readable TeX file though. However, there is a lot of thought into all of this because I wanted to make Madoko great for publishing papers and retaining full compatibility with any LaTeX packages and styles. (Just to clarify: yes, the custom environments still refer directly to the basic environments and commands and the class file you use will apply to those as always)

If you want more customization, the best way is through CSS rules directly in Madoko. If you really really need TeX commands directly, there are actually many hooks to apply TeX commands generally to certain elements, or CSS classes etc. It is not (yet) documented well but all in all quite powerful. (Btw. the custom styling is not by itself slower to compile in LaTeX -- it is mostly my lack of time to optimize this but that is certainly possible if a LaTeX expert would look at it.)

If we take a step back, the goal is really to have the defaults of styling being determined by any LaTeX package or style file and therefore all commands must eventually translate to a basic/common LaTeX one, for example, a # section should be a \section in LaTeX. Still though, we want to be able to apply CSS styling. Here there are two choices:
  1. output CSS key/values directly into the LaTeX and let TeX process these attributes and apply the right styling, or
  2. do a full translation on the Madoko side ofCSS style commands to the right LaTeX commands.
Now, we use 1 and it works very well across a wide range of styles and documents; but the output TeX is difficult to read. Nevertheless, it may be better to use option 2... especially when I consider how much time I have wasted on working around LaTeX insanity in the css.sty and madoko.sty style files. So, I think that in the future you may indeed get your wish granted :-) and I may move to option 2. For now though this is not a priority since the current translation works quite well.
Feb 10, 2015 at 7:26 AM
Thanks for clarifying your approach. I fully understand where you're coming from, and I'm really impressed with the degree of customization you've achieved in the sty files! I think the main issue here is not Madoko but LaTeX's insanity as you noted yourself.

Stepping back a little and thinking about the future of scientific writing (fully reproducible and more interactive and collaborative) it might make sense to focus your efforts on the HTML5 engine and ignore my plea for nice-looking and manageable TeX documents. I think what's really prevented researchers from embracing markup languages in my field (economics) has been the lack of support for manipulating tables (we make a living of producing complex statistical tables). Incidentally tables (and journal publishers) is also what's keeping us tied to LaTeX because til now there's no other option to produce good-looking tables. Equations used to be an issue as well, but that's gone to some extent now with MathJax and the likes. However with journals progressively moving to HTML as a new lingua franca (with embedded interactive tables and charts) we might be seeing LaTeX's final days. Not to mention ligatures and hyphenation are nearly there in CSS3.

A fast in-browser HTML rendering with a robust editor (e.g. document outline, syntax completion, table manipulation, etc.) that produces pleasing HTML that's easy to navigate (maybe using Bootstrap themes) and robust versioning and multi-user support (as you have it now) is probably what would convince the majority to move away from proprietary non-semantic formats. Also because most statistical packages still output summary tables in LaTeX we might need an engine that converts LaTeX (and simple CSV) tables to good-looking HTML tables.

I believe Pandoc/RMarkdown is following this approach but the majority of my collaborators don't use R, don't like command line tools, and they still need a GUI editor with a fast learning curve (yes, every researcher should know emacs or VIM, but let's be real here).

Of course I'd like you to implement approach 2 but maybe that's not as critical as improving the editor (to make it more attractive to non-techies) and releasing a Chrome app.

Would be good to hear from other users.