3 ms·

Skribilo: The Document Programming Framework

84 points by Tomte 2y ago

XorNot 2y ago
I'm sorry but this looks terrible. 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.]) ...imagine trying to write like this. It's essentially the opposite of what Markdown accomplished, which was taking a bunch of human conventions which were developed mostly out of ease of use (table formatting being the one which doesn't work well IMO) and adapting them so they can be parsed into nice text. Whereas this takes the most awkward possible syntax and completely ruins what you're looking at.
- Cyphase 2y ago
  To fix the formatting there: 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.]) The numbers on the left are line numbers, not part of the code.
  - XorNot 2y ago
    Just noticed that (HN formatting for quote embedding always surprises me). 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.
    - BenFeldman1930 2y ago
      That line of thought requires us to take unnecessary and costly effort to deduce structure from content. For example, finding a date in an e-mail body via regular expressions or NER tools. If the structure of the content is explicit, we know what part of the text is a date and what parts are not.
      - Skeime 2y ago
        While I do agree that extensibility is vital for a general tool like this (and Markdown isn't), I also think that it is necessary to make certain concessions to standard elements (like paragraphs) in a text. I think TeX and Typst get this right, for example, and writing text is the default, with light-weight markup for paragraphs. Both of them then have ways to still switch into "structured" markup where desired. 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.]) So there is the question whether using something like Skribilo would really save us from having to heuristically extract dates from e-mail bodies in practice.
- xigoi 2y ago
  > It's essentially the opposite of what Markdown accomplished, which was taking a bunch of human conventions which were developed mostly out of ease of use (table formatting being the one which doesn't work well IMO) and adapting them so they can be parsed into nice text. 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.
- __MatrixMan__ 2y ago
  I dislike defining a separate function for each link, but presumably one could chose to do that differently. Otherwise I think it's pretty nice. 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 is alt text](for some image). This doesn't have that problem.
kaynyn1 2y ago
Unless we have linters support for various IDEs and tools, it gets extremely annoying to keep adding tabs/spaces wherever required. Markdown shines in this aspect as I can take a basic vi and create a document that gets formatted to acceptable levels.
JonChesterfield 2y ago
I really like scheme. Strongly in favour of prefix notation. Still cannot imagine having the patience to write significant amounts of prose in this layout when commonmark -> s-expressions or XML or HTML is readily available. (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-syntax 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.
- neilv 2y ago
  > I really like scheme. Strongly in favour of prefix notation. Still cannot imagine having the patience to write significant amounts of prose in this layout 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/ All/most of the Racket documentation is written using Scribble now. I started writing a book about Racket using Scribble, so of course needed an Emacs mode: https://www.neilvandyke.org/scribble-emacs/ I've also adapted Scribble for API documentation embedded in source code. (After previously doing embedded TexInfo. Though, if I ever return to Scheme, I currently want to switch the embedded docs to Markdown, simply because lately I'm trying to promote a pragmatic, lightweight "Markdown everywhere" for software developers.)
NackerHughes 2y ago
Not to be confused with the online Pictionary clone Skribblio https://skribbl.io/ https://skribbl.io/
shrubble 2y ago
I have decided that "this is the year I learn Scheme" so this is very interesting, though it does look a bit intimidating; perhaps there is a "Skribilo-mode" in Emacs that makes it easier, though?
- danielvaughn 2y ago
  I'm going through SICP right now, and it uses Scheme. Just in case you aren't aware of it: https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/6515/sicp.zip/index.html https://mitp-content-server.mit.edu/books/content/sectbyfn/b... 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.
  - whilenot-dev 2y ago
    FYI there's also a JavaScript edition available: https://mitpress.mit.edu/9780262543231/structure-and-interpretation-of-computer-programs/ https://mitpress.mit.edu/9780262543231/structure-and-interpr...
benterix 2y ago
i have to admit this looks neat: (mark "self")
__MatrixMan__ 2y ago
I'm teaching a friend to code. We're not starting with a lisp, but I wanted him to understand why the idea of dispensing with bespoke syntax in favor of s-expressions is not crazy. That is, why the "soul" of a language is not its syntax. 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!

84 points by Tomte 2y ago

I'm sorry but this looks terrible. 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.]) ...imagine trying to write like this. It's essentially the opposite of what Markdown accomplished, which was taking a bunch of human conventions which were developed mostly out of ease of use (table formatting being the one which doesn't work well IMO) and adapting them so they can be parsed into nice text. Whereas this takes the most awkward possible syntax and completely ruins what you're looking at.

Cyphase 2y ago
To fix the formatting there: 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.]) The numbers on the left are line numbers, not part of the code.
- XorNot 2y ago
  Just noticed that (HN formatting for quote embedding always surprises me). 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.
  - BenFeldman1930 2y ago
    That line of thought requires us to take unnecessary and costly effort to deduce structure from content. For example, finding a date in an e-mail body via regular expressions or NER tools. If the structure of the content is explicit, we know what part of the text is a date and what parts are not.
    - Skeime 2y ago
      While I do agree that extensibility is vital for a general tool like this (and Markdown isn't), I also think that it is necessary to make certain concessions to standard elements (like paragraphs) in a text. I think TeX and Typst get this right, for example, and writing text is the default, with light-weight markup for paragraphs. Both of them then have ways to still switch into "structured" markup where desired. 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.]) So there is the question whether using something like Skribilo would really save us from having to heuristically extract dates from e-mail bodies in practice.
xigoi 2y ago
> It's essentially the opposite of what Markdown accomplished, which was taking a bunch of human conventions which were developed mostly out of ease of use (table formatting being the one which doesn't work well IMO) and adapting them so they can be parsed into nice text. 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.
__MatrixMan__ 2y ago
I dislike defining a separate function for each link, but presumably one could chose to do that differently. Otherwise I think it's pretty nice. 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 is alt text](for some image). This doesn't have that problem.

kaynyn1 2y ago

Unless we have linters support for various IDEs and tools, it gets extremely annoying to keep adding tabs/spaces wherever required. Markdown shines in this aspect as I can take a basic vi and create a document that gets formatted to acceptable levels.

JonChesterfield 2y ago

I really like scheme. Strongly in favour of prefix notation. Still cannot imagine having the patience to write significant amounts of prose in this layout when commonmark -> s-expressions or XML or HTML is readily available. (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-syntax 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.

neilv 2y ago
> I really like scheme. Strongly in favour of prefix notation. Still cannot imagine having the patience to write significant amounts of prose in this layout 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/ All/most of the Racket documentation is written using Scribble now. I started writing a book about Racket using Scribble, so of course needed an Emacs mode: https://www.neilvandyke.org/scribble-emacs/ I've also adapted Scribble for API documentation embedded in source code. (After previously doing embedded TexInfo. Though, if I ever return to Scheme, I currently want to switch the embedded docs to Markdown, simply because lately I'm trying to promote a pragmatic, lightweight "Markdown everywhere" for software developers.)

NackerHughes 2y ago

Not to be confused with the online Pictionary clone Skribblio https://skribbl.io/ https://skribbl.io/

shrubble 2y ago

I have decided that "this is the year I learn Scheme" so this is very interesting, though it does look a bit intimidating; perhaps there is a "Skribilo-mode" in Emacs that makes it easier, though?

danielvaughn 2y ago
I'm going through SICP right now, and it uses Scheme. Just in case you aren't aware of it: https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/6515/sicp.zip/index.html https://mitp-content-server.mit.edu/books/content/sectbyfn/b... 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.
- whilenot-dev 2y ago
  FYI there's also a JavaScript edition available: https://mitpress.mit.edu/9780262543231/structure-and-interpretation-of-computer-programs/ https://mitpress.mit.edu/9780262543231/structure-and-interpr...

benterix 2y ago

i have to admit this looks neat: (mark "self")

__MatrixMan__ 2y ago

I'm teaching a friend to code. We're not starting with a lisp, but I wanted him to understand why the idea of dispensing with bespoke syntax in favor of s-expressions is not crazy. That is, why the "soul" of a language is not its syntax. 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!