(item [Packages are available to produce: ,(ref :skribe %user-sui :ident "slides" :text [slides]) (overhead transparencies), ,(ref :skribe %user-sui :ident "pie-charts" :text [pie charts]), ,(ref :skribe %user-sui :ident "equations" :text [equation formatting]), ,(ref :skribe %user-sui :ident "programs" :text [syntax highlighting of computer programs]), and others.])
The signal to noise there is not good enough to compete. There's way too much repetition of annotation words.
The links to markup language and the simpler syntax were expected to tell me what the syntax is, not what a markup language is. Maybe the simpler syntax is more workable - the page doesn't show what that looks like.
edit found it in the docs, looks a lot more like markdown. https://www.nongnu.org/skribilo/doc/user-3.html#skribe-synta..., can't seem to link to the subheading.
So maybe this is a good thing with a landing page that drives newcomers away? Quite on brand for scheme if so.
The Racket people made a Scheme-based documentation formatter, called "Scribble", which includes a specialized syntax that's much more amenable to writing natural language text than s-expressions are:
https://docs.racket-lang.org/scribble/
I started writing a book about Racket using Scribble, so of course needed an Emacs mode:
https://www.neilvandyke.org/scribble-emacs/
This is an example on the main page:
(p [Skribilo is a ,(freedom [free]) document production tool that
takes a structured document representation as its input and renders that
document in a variety of output formats: HTML and ,(info [Info]) for
on-line browsing, and ,(lout [Lout]) and ,(latex [LaTeX]) for
high-quality hard copies.])
Whereas this takes the most awkward possible syntax and completely ruins what you're looking at.
121: (p [Skribilo is a ,(freedom [free]) document production tool that
122: takes a structured document representation as its input and renders that
123: document in a variety of output formats: HTML and ,(info [Info]) for
124: on-line browsing, and ,(lout [Lout]) and ,(latex [LaTeX]) for
125: high-quality hard copies.])
But I did know they were line numbers, I just wasn't going to strip them out - my point was that the scheme-style brackety inline syntax looks atrocious to try and write, follow or manage compared to the alternatives when the target is "documents" not "programming". Documents are first and foremost about content production.
Also, just offering the ability to introduce structure does not mean that it is done. For example, I could still write
(p [I write this comment on August 1, 2024.])
That comes at the cost of only having a few hardcoded features and not allowing extensions, making it hard or impossible to write anything non-trivial.
I tried to explain to my wife why markdown is better than google docs and we gave up when I was unable to justify the arbitrary choices re: [this is a link](to some place) vs . This doesn't have that problem.
He knows HTML already. Many do, we were raised by Myspace after all. So, this page turned out to be a great example of some nontrivial lisp to look at together. I also love how the code for the page is in the page, so you don't have to look elsewhere to see what it's trying to render.
I may or may not use the tool, but I'm quite happy it exists. Thanks!
It's a great introduction to s-expressions in general. I'm still early on but I love it and can see why it's a classic.
(mark "self")