I spent all of grad school writing everything in Markdown and converting to HTML, including my PhD thesis. It seemed like a harmless waste of time then but when I couldn’t get a humanities job, it meant I had a long term project I could point to when I was trying to get hired as a programmer. Moral of the story is always waste time.
Going the other way is much more tractable. Latex is tiring-complete.
https://www.w3.org/2004/04/xhlt91/ is what I cobbled together when faced with latex submission requirements. A quick search turns up several tools that look somewhat mature.
This raises the question - is there a better way to have one canonical scientific text that can be viewed as both a HTML document and an academic-formatted pdf? Maybe it’d be better to write an HTML page and convert that to latex? Or use some third markup language that can be easily converted into sensible latex and HTML?
PDFs are there because most papers were distributed in printed journals or conference proceedings (where they’d typically have required PostScript submission if the publishers didn’t do their own typesetting, but PDF gradually displaced PostScript, for very good reasons). They remained because they are a good archival format. Aside from that, they’re not a great medium for scientific publication. For example, you can’t sort or filter tables, you can’t change the scale or hide lines on graphs, and so on. Few people under the age of 50 print papers to read them.
HTML evolves too quickly and isn’t always great for long-term archiving. I’d love to see something that captured some of the dynamic behaviours of HTML, could be implemented in a web browser, and had both the good math rendering abilities of LaTeX and the ergonomics of a decent web page (reflowing for different screen sizes, pop-up glossaries, dynamic tables and graphs). Possibly just mandating a maximum version of various web technologies would work.
I think the theoretically right answer here is @media print. Use html as output format, browsers’s print button to convert that to PDF, and CSS to style that in the right way. HTML/CSS is an ok language to describe presentation of documents, browsers are an ok layout engine. Practically, this works for me for non-academic technical writing. Though, it’s not perfect: iiuc, browsers are ok, but not great layout engines, and support for print is not super complete (like, forcing a page break is this year’s feature).
I dream that I’ll use the following stack in five years for all kinds of technical writing:
https://deno.land/ as an implementation language with eval, out of the box tooling, static types and nice syntax
asciidoctor-web style “template as a JS function” (https://github.com/Mogztter/asciidoctor-web-pdf#custom-layout) for defining transformation from djot to output. This should make sure that users are always in control of the output, and can easily tune it (and that’s why implementation language matters a great deal)
(Subset of) HTML as the default output format, for viewing in browser
“Convert to PDF” function for archival purposes which uses browser’s ctrl-P or (ha-ha) implements it’s own rendering engine for non-interactive subset of HTML.
I wrote mine in HTML (hand written, prettier+linting+ide saved me from as much manual formatting as possible)
Going from HTML to PDF is infinitely easier (gotenberg or just double click the file and ctrl+s save as pdf)
And for some things where I’ve required reusable components etc I’ve just used a simple statically rendered React app, works a charm!
Also I’ve seen Markdown plus extensions work well for this when you need scientific notations or formulae. The tooling is still a little immature though.
Sphinx (rST) solves many of the cited problems. I’ve seen several Sphinx-generates theses that meet many technical requirements (MathJax; Unicode; complex tables) and are also formatted for PDF and HTML.
I spent all of grad school writing everything in Markdown and converting to HTML, including my PhD thesis. It seemed like a harmless waste of time then but when I couldn’t get a humanities job, it meant I had a long term project I could point to when I was trying to get hired as a programmer. Moral of the story is always waste time.
Related: https://willcrichton.net/nota/
Going the other way is much more tractable. Latex is tiring-complete.
https://www.w3.org/2004/04/xhlt91/ is what I cobbled together when faced with latex submission requirements. A quick search turns up several tools that look somewhat mature.
Well sometimes it is..
This raises the question - is there a better way to have one canonical scientific text that can be viewed as both a HTML document and an academic-formatted pdf? Maybe it’d be better to write an HTML page and convert that to latex? Or use some third markup language that can be easily converted into sensible latex and HTML?
PDFs are there because most papers were distributed in printed journals or conference proceedings (where they’d typically have required PostScript submission if the publishers didn’t do their own typesetting, but PDF gradually displaced PostScript, for very good reasons). They remained because they are a good archival format. Aside from that, they’re not a great medium for scientific publication. For example, you can’t sort or filter tables, you can’t change the scale or hide lines on graphs, and so on. Few people under the age of 50 print papers to read them.
HTML evolves too quickly and isn’t always great for long-term archiving. I’d love to see something that captured some of the dynamic behaviours of HTML, could be implemented in a web browser, and had both the good math rendering abilities of LaTeX and the ergonomics of a decent web page (reflowing for different screen sizes, pop-up glossaries, dynamic tables and graphs). Possibly just mandating a maximum version of various web technologies would work.
That’s what I’m working on: https://xidoc.nim.town/
I think the theoretically right answer here is
@media print. Use html as output format, browsers’s print button to convert that to PDF, and CSS to style that in the right way. HTML/CSS is an ok language to describe presentation of documents, browsers are an ok layout engine. Practically, this works for me for non-academic technical writing. Though, it’s not perfect: iiuc, browsers are ok, but not great layout engines, and support for print is not super complete (like, forcing a page break is this year’s feature).I dream that I’ll use the following stack in five years for all kinds of technical writing:
ctrl-Por (ha-ha) implements it’s own rendering engine for non-interactive subset of HTML.I wrote mine in HTML (hand written, prettier+linting+ide saved me from as much manual formatting as possible)
Going from HTML to PDF is infinitely easier (gotenberg or just double click the file and ctrl+s save as pdf)
And for some things where I’ve required reusable components etc I’ve just used a simple statically rendered React app, works a charm!
Also I’ve seen Markdown plus extensions work well for this when you need scientific notations or formulae. The tooling is still a little immature though.
Moving on to the thesis itself, the abstract is written in English, French and German, the French version being in verse!
Sphinx (rST) solves many of the cited problems. I’ve seen several Sphinx-generates
thesesthat meet many technical requirements (MathJax; Unicode; complex tables) and are also formatted for PDF and HTML.