HTML or Markdown as the primary source format

[erlend-sh]

As a continuation of #7:

My main gripe with the way the Archetypes project is set up at the moment is that it doesn't lend itself very well to open source contributions. If the goal is for Archetypes to be a living document maintained by an open source community, editing in LaTeX rather than the far more mainstream HTML or Markdown languages might turn off a lot of prospective contributors.

On that note, is there any chance of moving away from the LaTeX-first workflow? I understand that it's probably part of a tried and tested workflow at OTS constructed to appease the requirements of what I imagine is primarily enterprise clients. It just strikes me as a little bit backwards to wrangle a LaTeX document into an HTML page instead of the other way around.

The way I imagine the Archetypes report working is:

• Every year a new PDF report is published
• Throughout the year that follows, a living HTML document is continuously edited and added to by open source contributors
• The next year, a new PDF report is published, based on the updated data in the HTML document plus any new findings from OTS' research.
• The living HTML document is updated to match the latest report, and a new round of editing begins.

LaTeX wrangling should only be necessary once a year, and might not be necessary at all if a modern static site generator like Gatsby is used to export PDF files based on a print-specific template.

[bobchao]

+1, this also benefited l10n works since we will be able to leverage tools around HTML document localization.

[kfogel]

Hi, @erlend-sh and @bobcha.

We've been thinking hard about this. @erlend-sh, you're right that the current LaTeX infrastructure is tied very closely to our normal document-editing workflow, which is indeed oriented around reports written for enterprise clients. But the archetypes report is different from our usual reports: it has the possibility of long-term community engagement, and it really would benefit from Web-first or at least Web-also publication.

The polished PDF that Mozilla put together for the first version is very handsome, and we want the same level of production values for v2... but I'm not sure it's any harder for them to achieve that from a web page than it is currently from LaTeX anyway.

@bobchao your point about l10n is a strong one.

@jvasile and I will discuss and update here!

[kfogel]

Also, if anyone has hints on reasonably non-lossy automated LaTeX->HTML (or better yet LaTeX->foo where "foo" is any structured format) conversion, we're all ears. See this thread.

[kfogel]

@ruphy, thoughts?

[jvasile]

@kfogel and I had a discussion about this yesterday and came to the same conclusion: everybody struggles with a format that will make a decent doc and also make a decent website and is also easy to edit. The tooling is lacking, the formats are lacking, LaTeX is awesome and terrible, etc. I have some thought that HTML/CSS aimed at both print and web is the answer, but I don't actually have a path forward on that. If anybody has wisdom and experience on how we might manage HTML/CSS for print on this doc, I'm all ears.

[joshgay]

I think markdown -> latex -> pdf or restructured text -> latex -> pdf could be possible via pandoc by making use of some of the bells and whistles of pre-processing/post-processing. One thing that is good to know is that a "pandoc -f latex -t markdown" brings you really close to where you want to be and I think you could get there in a day's work. https://github.com/joshgay/open-source-archetypes/blob/markdown/open-source-archetypes.md