PreTeXt: Write Once Read Anywhere Authoring and Publishing System | Hacker News Reader

PreTeXt: Write Once Read Anywhere Authoring and Publishing System

pretextbook.org

74 pointsteleforce31 comments

I've written my bachelors thesis (mostly) with Markdown and Pandoc. You can just insert TeX commands in your Markdown and pandoc will recognize and pass them. It's really neat.

I don't think I would have wanted XML documents as sources. I felt like Markdown was a successful step away from any XML-inspired tag formats. Most books don't have a complex hierarchy. They just have paragraphs and titles.

If you ever have experience with structured text and a large document requiring re-use and perhaps even internationalisation, you'll see why XML is the optimal choice.

Now this did intrigue me quite a lot until the very second I looked at the example's "source code" and saw it's all XML.

Might I recommend https://github.com/typst/typst ?

I am writing a book, but it is a active learning book. Half the content and tasks in the book are coding based, and the other math based.

Due to the coding based, I am writing the book in Jupyter notebooks. But, writing the content in Jupyter is quite limiting. The main problems are the lack of automatic numbering of equations and automatic referencing.

There used to be an extension for Jupyter notebooks that does this [1] but is no longer actively maintained and doesn't work on Jupyterlab.

[1] https://github.com/jfbercher/jupyter_latex_envs

Your probably are avoiding pretext, but if you were interested, you could have <sage/> blocks that specify your language (say, Python, much like a jupyter kernel). You’d then write around your code blocks, just as you’re doing now, but heavy markup gives you the choices like referring to equations and such.

https://pretextbook.org/doc/guide/html/overview-sage.html

I have done various kinds of book authoring in the past couple years. I loathed my time in PreTeXt. I have strong feelings about staying in Markdown from now on.

I wrote a book in it[1] - I like that PreText takes care of every format at once, transpiling to whatever my desired output.

The interactives that are available in my html book without additional work are great (sage math, revealing solutions, embedding video solutions).

It’s a cumbersome language, sure, but it accomplishes some powerful things if you’re patient.

[1] https://Wichita.edu/discretebook

Sorry dude. I'm not writing my next book in XML.

Nice. It far exceeds my write-only publishing system

doesn't quarto do the same thing but a better job?

Their code README says

> PreTeXt is guided by the following principles:

> 1. PreTeXt is a markup language that captures the structure of textbooks and research papers.

> 2. PreTeXt is human-readable and human-writable.

When did XML become human readable and writable?

XML is a great choice for this because it's a markup language: it's designed for adding structure and formatting information to documents in a way that's generic and extensible.

Something like Markdown is too spartan for all the kinds of things you need to make a technical document.

XML may be a good choice to markup the structure and formatting of a technical document.

That doesn't make it a good human readable and writable format.

Notice that the description didn’t say it was a good format in that regard.

Aha, very true! It is human readable and writeable after all, just not very pleasant.

The ideal interface would be a WYSIWYM (what you see is what you mean) word processor like app that let you edit the markup visually, but using a semantic representation rather than strict WYSIWYG. Thus you can write without having to know too much of the syntax, but still be producing strict markup. I recall such editors existing about 20 years ago. I guess the market for XML tool died.

You just described Obsidian. Its UX atop .md files is simply amazing.

Logseq is another contender in this vertical: https://logseq.com/

For maths and scientific publications with WYSIWYG approach check TeXmacs:

https://www.texmacs.org/tmweb/home/welcome.en.html

Please note that despite the name it has nothing to do with TeX or Emacs.

No reason tooling can’t help with the reading and writing.

The computer is supposed to read xml, not people.

XML isn’t my first choice most days but there exist cases where it still readily flexes past other option no matter how popular.

Yeah, Markdown's not really a print document format. But LMLs (lightweight markup) don't begin and end with Markdown.

Asciidoc, on the other hand . . I've written aircrew flight checklists, component maintenance manuals, typescript developer documentation, illustrated parts catalogues, maintenance handbooks, operation guides, and a good-old-fashioned novelette in Asciidoc. Last few years with VSC. It's fast as hell. I got Asciidoc include for re-use, I got Asciidoc conditionals, VSC snippets, I got a billion other toys like textql, diagrams, wireviz.

And yeah yeah yeah, I know, it's cheating: Asciidoc is DocBook, DocBook is XML. Except Asciidoc's not XML. Asciidoc renders in Chrome/Firefox/Edge extensions, Ruby, JS, Python, and it exports to DocBook, LaTeX, PDF, HTML5, ePub, MOBI, MSO via DocToolChain or Pckr and, well, hell, bring in Pandoc if you want something else. When it comes to the Asciidoc tools, I can go from bare metal to full-up publishing environment in ten minutes. And how do I render DocBook again?

Oh, the XML pipelines. Those pipelines.

Schemas breaking XML spec[1], "XML-aware" diff/merge, whitespace[2], sneaky goddamn proprietary entities[3], namespaces, 1NF, computability[4], charset, semantic-less, hierarchy fetishism, etc etc etc blabbity blabbity blah.

I just realized this post sounds really frickin' angry, and I want to take a line here to say that I love all ya'll, but XML publishing has left some scars, and I'm sorry about that.

[1] "Leading whitespace in attributes? CHARMING"

[2] No such thing as "officially normalized" when it comes to XML whitespace, which means no lines, no tabs, no spaces.

[3] Goddamn REVBARS

[4] Ah, infinite arbitrary nesting, what a perfect fit for natural language

+1 asciidoc is where it's at. Given its strengths and similarity to markdown, I wonder why it hasn't taken off to the same extent.

the most famous example I know of: https://docs.atlas.oreilly.com/writing_in_asciidoc.html

Honestly, the first guide that comes up when you Google, asciidoctor, is bad. I just checked if it had improved and it starts talking about "If you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.", without defining assigning, and before I've been told how to put in a header. I got annoyed around there and went back to markdown.

That's from the writer's guide, which sucks. I'd hit the official doc site here: https://docs.asciidoctor.org/asciidoc/latest/. They rejiggered the docs with Antora oh, eh, four or so years ago.

But before I say anything else, if your use case is satisfied by Markdown, there's no reason to go anywhere else. Asciidoc's when you need more complex functionality: transclusion, conditionals, complex tables, weird print formats, ToC/LoT/LoF, indices, etc.

The main reason is that the processor was never JS-native. First Python, then Ruby, and then it got transpiled all over. Sure, today Asciidoctor.js is damn slick, but it took a while, and Opal.js has had some rough shakes.

The second reason - and a close tie with above - is that features aren't free. *Asciidoc is more complex than Markdown*, no way around that. The fact that you can also monkey around with transclusion and conditionals doesn't help things either - you can really dig yourself into a hole with transclusion unless you plan things very very carefully.

Digression: I want to expand on that point a moment. Document engineers have known that transclusion+conditionals were problematic functionality since 1994; it's why HTML never got transclusion as a core function, it breaks natural language documents. All the DITA/xinclude/"content re-use" people came from outside the initial technical GML/SGML group, and DITA architects were exclusively polisci/psych/pedagogical academics. There were some raised voices in the late 90s/early aughts, which we're still paying for to this day. Note that Antora - the Asciidoc build system - has an "opinionated" architecture, it's for this same reason: managing the complexity of transclusion. OK, digression over.

The third reason is the name. All due respect, but "asciidoc" is kind of meaningless, they'd have been better off drawing a clearer line between Asciidoc and DocBook. Something like LiteBook, or DocDown. "Asciidoc" though, makes a connotation that the central feature is the text encoding, and that's not really a substantial selling point. Having that DocBook lineage is; that's like Return of the King kind of lineage, if Aragorn had been lost in the XML wilds and then returned to the old design philosophy of GondorML to marry a hot elf.

Also, in case it matters to anyone: IJ plugin! https://plugins.jetbrains.com/plugin/7391-asciidoc (Apache 2: https://github.com/asciidoctor/asciidoctor-intellij-plugin/b... )

Poor design is also design

And markdown isn't the only alternative to the ugliness of XML

> When did XML become human readable and writable?

1996

> When did XML become human readable and writable?

Actually XML was designed as delivery not authoring language by giving up SHORTREF (= custom lightweight markup), tag inference, and other short form syntax XML inherited from SGML as its superset. There's even an attempt to bring back lightweight markup into XML ("Invisible Markup") though I personally can't see why they don't just use SGML for this which is an international (ISO) standard since 1986. 1986 or earlier is also about the point in time since when nerds invent their own plain text syntax and processing pipelines - not out of necessity mind you but clearly out of procrastination and fun when SGML (and TeX/LaTeX and run-off) has existed since.

Reply on news.ycombinator.com