Page 1 of 1

⛩️📰 书社

Posted: Sunday, 12 January 2025 @ 13:14 EST
by Lady
This topic is for discussing ⛩️📰 书社, the static site generator I’ve been developing for the past year. The basic idea is to use X·S·L·T to transform maintainable source files into complete webpages, and G·N·U Make for dependency tracking to speed up the build times.

The feature·set has expanded as I’ve tried to do more things with it, but it’s pretty stable at this point. I’ve been intending to make a 1.0.0 release for a while, but haven’t quite managed it yet.

Re: ⛩️📰 书社

Posted: Monday, 13 January 2025 @ 22:31 EST
by synchro
wait omg this is really damn cool! i don't ever think i've seen something like a static site generator that's XML and makefile based. i might have to give this a try even though i don't know XML stuff at all (<-- can barely make an RSS feed from scratch lol)

Re: ⛩️📰 书社

Posted: Monday, 13 January 2025 @ 23:18 EST
by Lady
synchro wrote: Monday, 13 January 2025 @ 22:31 EST wait omg this is really damn cool! i don't ever think i've seen something like a static site generator that's XML and makefile based. i might have to give this a try even though i don't know XML stuff at all (<-- can barely make an RSS feed from scratch lol)
Prior art is Shrine-XSLT, which was my first attempt at doing this sort of thing with X·S·L·T (and might be more comprehensible lol); I did a lot of Pandoc+Makefile stuff before that. I really like (G·N·U) Make as a basis for generating static websites because it’s broadly available and only regenerates what you need. You can do a lot with it if you can figure out how to make good use of its features, and thankfully the G·N·U Make manual is very comprehensive.

Initially, the goal was to have a minimal and easy means of inserting headers and footers into pages without all of the weight of a traditional static site generator, but as I’ve gotten more comfortable with X·S·L·T the scope has grown somewhat. In line with my fifth programming resolution for 2024 I’ve tried to commit fully to forward‐thinking and easily‐transformable formats, of which X·M·L is near the top of the list, mostly out of exhaustion from ever having to migrate anything. So I ask myself “what is the easiest way to represent this in X·M·L” and then “how do I transform that into something which is durable and future‐proof” and then “how do I transform that into a use·able webpage”, which is the situation with things like https://vocab.ladys.computer (source) which starts out as a simple, bespoke X·M·L dialect which is easy to write and lint with a D·T·D, is transformed into an R·D·F representation which is future‐proof and can be loaded in things like Protégé, and then is transformed again from there into all of the numerous X·H·T·M·L pages which are hosted on that site.

This is a lot better than my previous solution to this problem, which was built in Jekyll with a bunch of Yaml and Markdown and Liquid templating and simply was not ever portable to any other build system, even though I hated Jekyll and cringed every time I had to use it. Using X·M·L means that if I ever change how I do things, I just need to write a transformation to convert the old files into the new files and that’s a lot more straightforward.

Anyway, I do recommend learning about X·M·L and X·S·L·T, even though the X·M·L specification is hard to read and nobody has good learning resources for either anymore. (Only version 1.0 of either is relevant to the present day, because that’s all browsers or tools like libxml2/xsltproc ever implemented, even tho there is an X·M·L 1.1 and an X·S·L·T 2.0 & 3.0.) So, let me know if you encounter any stumbling blocks there, because it’s entirely reasonable. The examples section at the end of the X·S·L·T specification might be a reasonable place to start; if you can figure out how those work then you have the broad grasp of things.

Re: ⛩️📰 书社

Posted: Tuesday, 14 January 2025 @ 11:14 EST
by alyssa
hm, on this glance through the README, certain aspects definitely seem helpful for some of my main website/page-making purposes, but it's a bit hard to tell how smoothly it would work for some of the other bits. nowadays i mainly make webpages for two purposes: conlangs and rules summaries/references for ttrpgs. the embedding seems useful (for e.g. integrating lexicons, separating out subdocuments in the source, or sharing important tables between a rules summary and a cheat sheet), and maybe some of the transform features could be used to do stuff that has previously led me to resort to HTML custom elements to handle repeated rules structures.

the thing i'm least clear on, though, is what does one do for stuff that's just, a text, in 书社. large chunks of my rules summaries (and conlang descriptions) are just text formatted for readability and easy reference (currently written mostly in markdown and HTML respectively). would that just be (X)HTML with less transformation going on in 书社?

Re: ⛩️📰 书社

Posted: Tuesday, 14 January 2025 @ 12:48 EST
by Lady
alyssa wrote: Tuesday, 14 January 2025 @ 11:14 EST the thing i'm least clear on, though, is what does one do for stuff that's just, a text, in 书社. large chunks of my rules summaries (and conlang descriptions) are just text formatted for readability and easy reference (currently written mostly in markdown and HTML respectively). would that just be (X)HTML with less transformation going on in 书社?
It can be! I think there are a few options:
  • Write the text in a simpler markup language, like LesML, which parses to XHTML. For dictionaries I’ve found this approach to be a bit limited.
  • Write the text in TEI dictionary markup, and then use a parser (or transform) to convert that to XHTML.
  • Write the text in a bespoke XML format which is simpler, and parses to TEI or XHTML.
  • Just write the text in XHTML to begin with.
⛩️📰 书社 is definitely targeting text in the sense that XHTML has a lot of boilerplate which it is a struggle to maintain. By default, it wraps HTML elements in <html> and <body> tags and you can throw things in the head easily by yielding them from a transform in the 书社:metadata mode. So you can just use it exclusively for that, and ignore the parsing and other transformation features. That’s kinda where I started.

What I personally found tho is that once you have a transformation engine set up, it’s hard not to want to use it to simplify other things you are doing as well. It really enables you to get at the heart of semantic markup without worrying about presentation. So I typically don’t write as much pure HTML anymore, and instead go with something closer to my intent.

Anyway, I definitely will definitely be using ⛩️📰 书社 for conlanging stuff eventually, so I can share that with you once I get it set up. I just haven’t quite finished all the prerequisite work yet…

For a simpler, Mostly Just XHTML example, see the source code to my website. This is a much more straightforward case where I’m mostly just using it to reduce boilerplate and not doing much at all with the parsers/transforms.