Re: How stable is AsciiDoctor?

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: How stable is AsciiDoctor?

mojavelinux
Administrator
I want to start by making it very clear that the Asciidoctor project is the home of the AsciiDoc syntax. Asciidoctor runs on every major services that supports AsciiDoc and most integrations have switched over to Asciidoctor at this point. AsciiDoc Python is where AsciiDoc originated, but Asciidoctor is where it lives on.

I do want to see the definition of AsciiDoc separated eventually from the processor, but we haven't crossed that bridge yet. I envision a versioned specification at some point in the future (I just haven't been able to make that commitment yet).

> I wonder if I could write diary and take notes in AsciiDoctor and keep it unchanged for decades or even centuries. Would my AsciiDoctor documents compile without problems after 3 decades? Would they after 100 years?

On the one hand, there's no way I could guarantee that. Will we even have computers then?

On the other hand, that's the whole idea of AsciiDoc. It's plain text. You can always parse it. You can even print it and transcribe it with pen and paper.

> I want document archival. 

If your goal is document archival, I'd recommend DocBook instead. The goal of AsciiDoc is to make writing, especially highly technical and structured writing, easy and enjoyable. It's not designed to be an archive format. That's really where DocBook comes in and why one of the core converters in Asciidoctor produces DocBook. These two languages are companions in many ways (though certainly not exclusively so).

> If AsciiDoctor is likely to introduce breaking changes, is there a stable subset of AsciiDoctor that's not likely to change?

It's pretty safe to say the core syntax patterns in AsciiDoc are not likely going to change (delimited blocks, macros, preprocessor directives, lists, etc). When we do make a substantial change to the syntax, we'll probably use a new name for that syntax (something like UniDoc). That would signal to writers to expect a certain amount of differences. (Though that's by no means a final decision). But we'll definitely continue to make tweaks to AsciiDoc to improve it within the boundaries of that core syntax.

Keep in mind, you can always just fix the version of Asciidoctor you are using. Older versions will always remain available, so that's one approach you can take to guarantee stability for eons.

I want to finish be reiterating what I see as the goal of Asciidoctor. The goal of Asciidoctor is to give writers a powerful tool to create highly technical documents using concise, comprehensible markup, and to be able to transform that content in a myriad of ways so as to get the most use out of it. Yes, compatibility is a goal, but we have to balance that with evolving the syntax. And I can't predict the future.

-Dan


On Sat, Jul 29, 2017 at 7:04 PM, egalitarian [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Evernote was inconvenient to use because it didn't support deep note hierarchy.
I was trying to use CommonMark for diary and note-taking. CommonMark seemed ok for those purposes.
I expect CommonMark to stay stable for a long time because it is a versioned specification.
However, I was drawn to AsciiDoc because it has more features like inclusion, admonition, and table.

It seems that asciidoc is slowly dying and asciidoctor is a different format than asciidoc.

I wonder if I could write diary and take notes in AsciiDoctor and keep it unchanged for decades or even centuries.

Would my AsciiDoctor documents compile without problems after 3 decades? Would they after 100 years?
If AsciiDoctor is likely to introduce breaking changes, is there a stable subset of AsciiDoctor that's not likely to change?
I want document archival.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-stable-is-AsciiDoctor-tp5771.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: How stable is AsciiDoctor?

egalitarian
So, to maximize longevity, I should stick to the core syntax and convert AsciiDoc to DocBook.

I think AsciiDoctor is already good for note-taking. For diary which benefits more from long-term archival than from markup capabilities, I might want to keep looking for more alternatives before settling down.
Reply | Threaded
Open this post in threaded view
|

Re: How stable is AsciiDoctor?

egalitarian
In reply to this post by mojavelinux
I let AsciiDoctor sink in my mind for a while. I concluded that the combination of the AsciiDoctor core syntax and DocBook is stable enough for diary. I surmise that as long as I stick to simple subsets of nested lists, sections, cross references, image macro, and perhaps table, my AsciiDoctor diary entries will last long. My opinion could change at an unknown point in the future.

I considered commonmark, too. It's simple, but, it doesn't handle nested lists nearly as well as AsciiDoctor.

For note-taking, the format is ok. The problem is to name and organize notes on a file system, but that's beyond the scope of this thread.
Reply | Threaded
Open this post in threaded view
|

Re: How stable is AsciiDoctor?

mojavelinux
Administrator
That's great to hear!

I certainly welcome your input on any decisions that are made about the project as development proceeds. This project is first and foremost about the writers.

Cheers,

-Dan

On Aug 5, 2017 21:09, "egalitarian [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
I let AsciiDoctor sink in my mind for a while. I concluded that the combination of the AsciiDoctor core syntax and DocBook is stable enough for diary. I surmise that as long as I stick to simple subsets of nested lists, sections, cross references, and perhaps table, my AsciiDoctor diary entries will last long. My opinion could change at an unknown point in the future.

I considered commonmark, too. It's simple, but, it doesn't handle nested lists nearly as well as AsciiDoctor.

For note-taking, the format is ok. The problem is to name and organize notes on a file system, but that's beyond the scope of this thread.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Re-How-stable-is-AsciiDoctor-tp5804p5808.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML