nips
nips copied to clipboard
nostr-protocol
nip54: change to asciidoc
== Why?
Because Markdown is somewhat of a mess. It's fine when you just use the core features, but when you start to add tables and other stuff it quickly degrades. And there had been talks already of how to add description lists, footnotes, sidebars and tables to these wiki articles so we would not be able to stick to mostly plain text anyway.
Asciidoc has a strict spec, multiple implementations in many languages, and support for features that are very much necessary in a wiki article, like sidebars, tables (with rich markup inside cells), many levels of headings, footnotes, superscript and subscript markup and description lists. It is also arguably easier to read in its plaintext format than Markdown.
Read this if you're still not convinced: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/
Caveat: I don't have much experience with Asciidoc (if I had I might have proposed this NIP with Asciidoc since the beginning anyway).
Caveat: unfortunately Asciidoc is extensible, so it is not guaranteed that implementations will all implement the same extensions and stay compatible forever. However the extensions at least are well-delimited, named and specified and must be added explicitly by the developer (unlike on Markdown world where each library will add ad-hoc extensions by themselves), so that should be less bad. Also it's always clear when an extension is being used since its usage is delimited in tagged blocks in the source text. In any case I think we won't need any extensions for a long time.
== Migration path
Option 1:: Just drop Markdown support and be done with it. Everything will still be readable. Option 2:: Documents created up to the date this document is merged should still be supported in the existing wiki clients. Documents with a higher timestamp shouldn't. Clients can drop Markdown support entirely in the future when that becomes a more reasonable idea.
@hzrd149 @pablof7z @SilberWitch
Clients will end up having to support every format anyway, so bring it on.
I like asciidoc better. But what about this: https://wikifreedia.xyz/nud:-nostext/npub1jlrs53pkdfjnts29kveljul2sm0actt6n8dxrrzqcersttvcuv3qdjynqn
Clients will end up having to support every format anyway, so bring it on.
I knew you were going to say this, but let me just say again that you are wrong!
I like asciidoc better. But what about this: wikifreedia.xyz/nud:-nostext/npub1jlrs53pkdfjnts29kveljul2sm0actt6n8dxrrzqcersttvcuv3qdjynqn
Looks like a simpler and more strict Markdown. Could be good for notes, but it's not powerful enough for wiki articles.
I knew you were going to say this, but let me just say again that you are wrong!
Prove me wrong and everybody wins.
Looks like a simpler and more strict Markdown. Could be good for notes, but it's not powerful enough for wiki articles.
Yeah, I'd go nuts trying to format articles with so few options. Like trying to edit a magazine or encyclopedia with nothing but .txt files.
Interesting. I'm apparently using some asciidoc formatting, thinking it was markdown, like italics . That explains why some of the clients aren't displaying them as expected.
I've seen the ==Header format in the articles I've referenced from Medium.com, so they seem to be using Asciidoc.
I support this change. 🤔 It's still early and markdown files stay readable, even without the rendering.
Interesting. I'm apparently using some asciidoc formatting, thinking it was markdown, like italics . That explains why some of the clients aren't displaying them as expected.
I've seen the ==Header format in the articles I've referenced from Medium.com, so they seem to be using Asciidoc.
I support this change. 🤔 It's still early and markdown files stay readable, even without the rendering.
Apparently, GitHub allows for both, as the italics rendering is correct.
https://wikistr.com/ has transitioned already and I'm slowly working on the change for Wikifreedia.
Okay, I saw that my files looked funny on wikistr. Now I'm sort of trapped, since some of them have changed, but some not, so I guess I'll just wait until everyone moves and then reformat.
@hzrd149 are you also aware of this change?
I saw this a month ago and looked into it little. It looks like a good format, but I'm worried there isn't enough libraries for clients to use for rendering. I also wasn't able to find any WYSIWYG editors for it, so most clients might have to implement thier own
I'm not opposed to this change, but I think there is a benefit to markdown even though it is a bit messy and missing features
We've added an optional "markup" tag to our 30041, so that someone can define if they used asciidoc, markdown, LaTeX, PlantUML, AsciiMath or whatnot in their article event, with markdown the default, if it's undefined.
We have to support a wider array because we're using the events for complex documents like scientific research papers and etc.
Might be an option for other article events. 🤷♀️
We've added an optional "markup" tag to our 30041, so that someone can define if they used asciidoc, markdown, LaTeX, PlantUML, AsciiMath or whatnot in their article event, with markdown the default, if it's undefined.
We have to support a wider array because we're using the events for complex documents like scientific research papers and etc.
Might be an option for other article events. 🤷♀️
Different formats should have different kinds; otherwise you just raise the bar to support a specific kind and increase the complexity for rendering it. Overloading kinds with different, even if adjacent, meanings and/or renderings is an anti-pattern.
Then we should reject this PR and stick with only markdown and come up with a different kind for Asciidoc.
We are basing our Kind 30041 off of this one and we assumed that allowed for markdown default.
I believe without Asciidoc (or some other markup language, suggestions accepted) the Nostr free encyclopedia will never attract the methodical people who love categories and structure. Markdown is too limited and clients will naturally start adding ad-hoc extensions to it to accommodate some needs, and these extensions will not be as complete as Asciidoc, but also they won't be standard enough and there won't be WYSIWG editors that support them uniformly anyway, so nothing will work and it will be chaos. @hzrd149
If I manage to finish my Quill integration then we'll have at least one WYSIWG editor for Asciidoc.
I am currently working in a WYSIWG editor for nostr based on tiptap / prosemirror, It supports markdown already and I would love to support Asciidoc too, and I agree this should be in a different kind.
Can we just have two different wiki kinds, one for markdown and one for asciidoc? Then the writer is free to pick the one they prefer.
It will usually be markdown, but some more complex documents could use asciidoc.
No. It must be one. Having two just doubles the work for everybody. We're still very early here and we can transition. But if everybody wants to remain on Markdown then please let me know so I can stop working on Asciidoc crap.
I don't see how we don't offer some event with asciidoc, long-term, without cutting off advanced publishing use cases. We were considering having asciidoc-blocks in markdown docs, but it seems to be easier, the other way around.
I also saw that there are PlantUML and LaTeX extensions for Asciidoc, which is awesome.
Yeah, okay, just looked at my wiki pages under Asciidoc and they look nearly the same. Only the more advanced stuff that only I'm using is even different.
Most people could keep writing markdown and wouldn't even notice the difference.
https://github.com/fiatjaf/quill-asciidoc @hzrd149 https://github.com/fiatjaf/svelte-asciidoc https://github.com/pablof7z/wiki/pull/32
Okay, GitCitadel is going to host Wikistr, we're rewriting our docs into asciidoc, and our products will use @fiatjaf 's asciidoc libraries. Done.