Author Topic: Looking for AsciiDoc editor (Read 16281 times)

Shades · « **on:** June 08, 2019, 12:31 PM »

For documentation purposes, I have suddenly a need for an AsciiDoc editor. AsciiDoc is a text based format and in essence even the the standard notepad in Windows is able to create AsciiDoc documents. In many ways it is similar to Markdown, yet it also isn't. The receiver of this documentation is dead set on AsciiDoc and will not hear of anything else.

For Markdown there are quite a few editors that make the creation of Markdown documents a lot easier. For AsciiDoc, not so much.

Google hasn't helped me much when looking for AsciiDoc editors. All my searches revealed two editors: AsciiDoctor and AsciiDocFX
AsciiDocFX looks reasonable and has some features that are good, but there are also many quirks. Furthermore, it is also Java based (which is not a favorite of mine) and has leaks RAM if you leave the application open too long. You could compare it to editing documents "under water" in Word Perfect, except with a vertical split, instead of a horizontal one. So it is workable for someone who is acquainted with that style of working. Or someone like me who is (too?) familiar with wiki markup and editing.

There is also Visual Studio Code that has an AsciiDoc extension, but it isn't nice to use, because the preview and the text are not "linked". As in: click on the preview and the edit section doesn't "follow" to the location where you clicked in the preview and vice versa. Yet it is nicer to use than chopping up the Eclipse IDE (Java again) to turn it into an AsciiDoc editor.

However, for those generations that grew up with Office and Word, any of the above options that will be a hard "sell". In essence, I am looking for an editor that looks like Word or Wordpad, with similar features as AsciiDocFX.

GitHub shows a lot of converters and plugins related to AsciiDoc, but not editors (at least not in the first 10 pages of their website's search results). SourceForge, Codeplex, PasteBin and others from this repository list are also a bust.

Does anyone here have any more ideas where I could find such software?

jeromg · « **Reply #1 on:** June 09, 2019, 01:48 AM »

Hi Shades, maybe you've already thought about it, I'm not familiar with AsciiDoc but I would recommend editing in markdown (but I may be biased since I do everything in markdown these days) and converting to AsciiDoc using pandoc, see here for examples.

Cheers /jerome

wraith808 · « **Reply #2 on:** June 09, 2019, 01:26 PM »

It's at times like this that we had a simple way to vote up. Been a bit busy today, but planned to answer exactly the above.

jeromg · « **Reply #3 on:** June 09, 2019, 04:03 PM »

hehe

Shades · « **Reply #4 on:** June 09, 2019, 04:05 PM »

Hi Shades, maybe you've already thought about it, I'm not familiar with AsciiDoc but I would recommend editing in markdown (but I may be biased since I do everything in markdown these days) and converting to AsciiDoc using pandoc, see here for examples.

Cheers /jerome
-jeromg (June 09, 2019, 01:48 AM)

Don't worry, not many people are. Which is also why AsciiDoc software is in the state it is. And if you would ask me, Markdown would have been fitting the documentation bill just fine. Heck, even a wiki would have been sufficient. But not my call. Actually, there is one person at the company receiving the documentation, who made a ruckus about AsciiDoc and now we are all stuck with it.

Before this, I had never heard of AsciiDoc. Gaining this knowledge did not improve my career or life in any way. And continuing with this honesty, it feels like a person or group of persons thought about making a standard better than the 10 earlier attempts of making the standard for documentation. Result? AsciiDoc is now the 11th standard.

While I am put in charge of converting existing documentation to AsciiDoc, those that need/want to make new documentation are not willing to give up their Word GUI habits/mindset to go back 20 years GUI concept-wise. For myself and my work-flow, the current AsciiDoc editors are adequate. As a proponent of wanting to separate content from layout, I don't use Office much anymore. Instead, I use PanDoc to generate the same document in whatever format the receiver wants.

Knowing full well that I am weird this way (and probably many other ways too) I can't expect everyone to work like this. Actually, it is my opinion that most people would not be able to create documentation without an Office suite anymore. Or even want to, for that matter.

To get a better/quicker adoption of AsciiDoc, it would be a big benefit to have software that enables people with "Office"-mindset to work as they are more or less used to. Hence my request for a new place where to look for AsciiDoc editors that look like Word/WordPad. Asking those same people to work with PanDoc, a command-line tool, to convert MarkDown to AsciiDoc, I think that would be too much. For myself though, your idea has merit.

It would seem better just to wait patiently until AsciiDoc software improves before pushing it onto others. In the mean time I'll make scripts to handle the conversion of existing documentation "automagically", reducing that headache for myself.

ewemoa · « **Reply #5 on:** July 08, 2019, 08:00 PM »

There is also Visual Studio Code that has an AsciiDoc extension, but it isn't nice to use, because the preview and the text are not "linked". As in: click on the preview and the edit section doesn't "follow" to the location where you clicked in the preview and vice versa. Yet it is nicer to use than chopping up the Eclipse IDE (Java again) to turn it into an AsciiDoc editor.
-Shades (June 08, 2019, 12:31 PM)

Which extension did you try specifically? I was also looking for something to write Asciidoc and I didn't have luck with the two I tried:

https://github.com/a...r/asciidoctor-vscode
https://github.com/b...r-asciidoctor-vscode

I also tried on the Atom editor where IIRC there is more than one, but no dice there either.

I'm stuck with AsciidocFx at the moment.

Shades · « **Reply #6 on:** July 09, 2019, 11:37 AM »

Still the same problem here. There are no real good AsciiDoc editors, unless you know the syntax by heart. Markdown has more mature editors, but it is cumbersome to create documentation in those and then do a conversion.

AsciiDocFX is currently the best of the bunch.

At the time I used VSCode v1.32 with the extension: AsciiDoc v2.7.6 from João Pinto (your first link). It is not bad, but the missing "link" between source section and the visualization section is a very big deal for me, as some pretty big documents need to be processed by me. Makes it way too easy to lose track of where you are and you'll start wasting time doing that instead of creating content/documentation.

The extension from your second link doesn't even appear in the extension tab of VSCode here in Paraguay (assuming there is some geo-policy present in the VSCode extension marketplace).

Now I have made a batch script that helps me to automatize the conversion of all Word documents to AsciiDoc in any given folder (and its siblings). While that makes converting an existing document collection a whole lot easier, it isn't that fast and after conversion you still need to check if the converted documents have the same layout as the original and/or fix possible "glitches".

ewemoa · « **Reply #7 on:** July 10, 2019, 12:12 AM »

There are no real good AsciiDoc editors, unless you know the syntax by heart.
-Shades (July 09, 2019, 11:37 AM)

As an Asciidoc newbie, I surely don't. Here's one thing I found tricky to figure out:

https://mrhaki.blogs...e-only-block-as.html

Do you happen to know of a list of 'gotchas' or other such not-so-obvious things?

Markdown has more mature editors,

Although there are so many varieties of "Markdown"...btw, do you think CommonMark will significantly improve this situation?

but it is cumbersome to create documentation in those and then do a conversion.

Indeed.

AsciiDocFX is currently the best of the bunch.

At the time I used VSCode v1.32 with the extension: AsciiDoc v2.7.6 from João Pinto (your first link). It is not bad, but the missing "link" between source section and the visualization section is a very big deal for me, as some pretty big documents need to be processed by me. Makes it way too easy to lose track of where you are and you'll start wasting time doing that instead of creating content/documentation.

Wow, double-clicking in the extension (seems to work better for me now) has some very odd behavior indeed. It's nice that AsciidocFX seems to work appropriately in that regard.

The extension from your second link doesn't even appear in the extension tab of VSCode here in Paraguay (assuming there is some geo-policy present in the VSCode extension marketplace).

Doesn't seem like much of a loss, as, although it installed here, not much luck in getting it to work

Now I have made a batch script that helps me to automatize the conversion of all Word documents to AsciiDoc in any given folder (and its siblings). While that makes converting an existing document collection a whole lot easier, it isn't that fast and after conversion you still need to check if the converted documents have the same layout as the original and/or fix possible "glitches".

Perhaps someday something better will show up at:

https://asciidoctor....c-with-live-preview/

Shades · « **Reply #8 on:** July 10, 2019, 11:47 AM »

I didn't try atom. I am not a fan of that bloaty thing to begin with, but your experiences with it do not sound so great, so I won't even bother trying it out...

Brackets feels like it is based on atom last time I tried it as a HTML editor, years ago. Never looked at it anymore. Might try it though.
Eclipse and IntelliJ IDEA were on my test bench in the mean time. And both disappointed in document creation as well. However, these can be used to tie directly into version control systems. If that is a requirement on your part (it is on mine), you could take a look at these.

Heck, I might even try atom, just to make sure I covered all the bases.

I had a need of escape characters (to prevent content being parsed as AsciiDoc content) and there are 2 ways to do that. On their forum I found a reference that didn't work at all. And it took me a while to find another method in a blog, completely unrelated to AsciiDoc. That one did work, though. From memory: parse:[]

From all my searches I did create my own AsciiDoc cheatsheet at work. I will add it here in due time.

Indentation inside another "object" can also be very tricky. There is a big word file I need to convert, that makes use of indentation in all sorts of ways. And that makes AsciiDoc conversion trip up like clockwork.
Converting more complicated structured word documents will give you lots more headaches.

wraith808 · « **Reply #9 on:** July 10, 2019, 12:28 PM »

CommonMark had the potential of standardizing things until the creator of Markdown spoke against it. Some people are avoiding it for just that reason. I've created documentation in Markdown before and output it to different formats quite easily using Pandoc, or even just the converter in Sublime Text.

Though there are many variations that implement different things that the baseline Markdown don't, I find that much of it is just window dressing.

Shades · « **Reply #10 on:** July 10, 2019, 08:23 PM »

When I look at MarkDown, I see that it was created with good intentions and a new, easier standard for documentation. Today there are many MarkDown dialects or standards muddying the "water", so to speak.

AsciiDoc looks like it is heading in the same direction already. For me, working with AsciiDoc requires me to remotely login and add/adjust documentation. The people behind that system chose Antara or Antera, so they can serve these AsciiDoc documents on their internal network by browser to the people that require this documentation. And some (basic) features of AsciiDoc are not a good fit for Antara/Antera, even though it is written to serve AsciiDoc files as HTML pages in a browser.

Maybe I am looking too fondly at the days gone by, where we would get a well written out specification for new software or addition and that everything needed to work exactly as described. With all this AsciiDoc hassle of late, I get the impression that too many people have too much influence by DevOps, user stories and what not. Not ideal for creating a standard and actually sticking to it.

And to be honest, setting off the amount of work being done by so many bright minds against the amount of improvements with lots of (new) software being created, I don't see the improvement side going up.

Well, guess that's my cue to apply for IT's grey beard club...

Deozaan · « **Reply #11 on:** July 10, 2019, 08:36 PM »

I'm reminded of this:

xkcd: Standards

ewemoa · « **Reply #12 on:** July 11, 2019, 07:08 PM »

Speaking of standards and specs...

https://asciidoctor....iidoc-spec-proposal/

Shades · « **Reply #13 on:** July 11, 2019, 08:32 PM »

Speaking of standards and specs...

https://asciidoctor....iidoc-spec-proposal/
-ewemoa (July 11, 2019, 07:08 PM)

Sounds like a plan!

Shades · « **Reply #14 on:** August 30, 2019, 11:18 PM »

Update time:

I have been very busy the last 2 weeks converting a document that has been growing for over 15 years. Not only is the document extensive, it is also filled to the brim with internal and external references. Although the document looks rather simple when looking at it in Word, it isn't and I suspect that got PanDoc a bit of it's rocker and produced a pretty big mess after conversion.

So the last weeks I have been busy "taking the document apart in the tiniest pieces, created templates for those pieces, repaired whatever was garbled up by PanDoc and start building it back up again.
In the mean time I have worked a lot with AsciiDocFX, Brackets (+ asciidoc plugin), IntelliJ Idea (v2019.2 Community edition +asciidoc plugin), Eclipse (+asciidoctor plugin), VSCode 1.37.1 (asciidoc plugin) and Notepad++ with asciidoc extension. The last one is more like a new programming language to be added for colored syntax. There is really nothing more to it.

My experiences so far:
All editors, with the exception of Notepad++, consume a boatload of resources when working on more complex documents. VSCode was the worst of the lot in my case. After 30 minutes or so, it would use around 6GByte of RAM and continuously between 80% and 90% of all CPU resources. Proper previews were a problem as well. Not a success.

Then I tried IntelliJ Idea. That also consumed almost as much RAM and CPU as VSCode did, but that was somewhat justified as the preview worked better, but it would also validate syntax/style and show you where you were making (minor) mistakes. While that last part is very handy when working with more complex documentation, it was still too much of a burden on this PC (A10 APU at 4GHz with 24GByte of RAM).

By that time, I was thinking "to hell with it" and used Brackets. Having tried that editor a few years back and not liking the experience one bit, this time around it was pretty nice to use with AsciiDoc. There is no real-time preview available, so it isn't consuming that much resources. You can however enable a preview at your convenience. The preview isn't as complete as the one from IntelliJ IDEA, but way better than the one from VSCode. There is also a section in the preview that shows you syntax/style errors (rudimentary, but still).

For "funsies", I also tried Eclipse again with the now nearly finished document. The real-time preview functionality in that editor is standing head and shoulders above the rest regarding rendering speed. A very pleasant surprise that was. It takes between 10 and 20 seconds to do a complete re-render of a document that describes almost 600 script commands and some of those are very extensive.

Feature-wise AsciiDocFX is the best, it's real-time preview isn't fast, but also not as complete as others, which limits my use for it. But Brackets and Eclipse were pleasant surprises, each in their own way.

So if you have relatively simple AsciiDoc documents to create, AsciiDocX is probably your best bet. For conversion and/or repair of existing documents (with some complexity), I would say to focus on Brackets and Eclipse. Brackets, if you have grokked enough AsciiDoc syntax and can work without real-time previews. Or Eclipse, if there is a need for a real-time preview that won't slow you down that much.

Oops, forgot about Notepad++. The syntax highlighting works rather well and as it is the least extensive editor of the bunch, it is pretty fast. But without a preview option, you'd better have a pretty firm grasp of the AsciiDoc syntax and have a very clear idea how you want your new document to be structured. That requires a lot of discipline, which people that code for a living have less issues with than other mortals. Its usefulness as AsciiDoc editor is therefore limited for most.

All of the editors discussed in this particular post can be used as a portableApp, if that is a thing for you.

Caveat:
AsciiDocFX can be finicky. I have used it on many different computers with lots of different versions of Windows and never gave any issue, until I tried it at home. There is a continuous error about the JVM not able to start because of max memory allocation. No matter what change I made in those settings, it just refused to start. Yet, IntelliJ and Eclipse are also Java-based and have no issue working on this system. Something I thought worth mentioning for those considering editors.

Nod5 · « **Reply #15 on:** September 01, 2019, 04:07 PM »

I confess I hadn't heard about AsciiDoc until reading this thread.

I then read https://asciidoctor....cs/what-is-asciidoc/ which asks two questions "What is AsciiDoc? Why do we need it?" but doesn't answer the most important question: why AsciiDoc rather than the much, much more common MarkDown?

I then found https://asciidoctor....sciidoc-vs-markdown/ and while mighty sceptical when starting reading I actually came out thinking AsciiDoc has some nice features. But mark down my words: I sure won't be an early adopter.

wraith808 · « **Reply #16 on:** September 01, 2019, 08:11 PM »

Nod5 summarizes my path through finding out about AsciiDoc quite well.

Shades · « **Reply #17 on:** September 01, 2019, 11:30 PM »

It was the same here. For my own uses I run a wiki and would have been happy to keep documentation that way. Mark down would have been my second choice at that time. And at that point in time I had never heard of (or cared about) AsciiDoc either.

But I have been going through the manuals of both Mark Down and AsciiDoc, have gotten quite some experience with Asciidoc and it is easier to write documentation in AsciiDoc and the syntax is more human-readable than Mark Down (especially when you start to use more complicated items/structures in your documentation).

By all means, keep using what you are familiar with. This whole thread started as a question, but could be seen as a reference or starting point now. For those in need, of course. And if I find new and/or better tooling for working with AsciiDoc, I'll update this thread again.

ewemoa · « **Reply #18 on:** September 02, 2019, 10:47 PM »

Somehow I missed the extensive experience report -- thanks a lot of that, Shades.

Luckily, I only have small docs to work on ATM.

Nod5 · « **Reply #19 on:** September 03, 2019, 05:50 AM »

This whole thread started as a question, but could be seen as a reference or starting point now. For those in need, of course. And if I find new and/or better tooling for working with AsciiDoc, I'll update this thread again.
-Shades (September 01, 2019, 11:30 PM)

Thanks for documenting your experiences - useful! I hope plaintext readable document formats in general get more widely adopted.

wraith808 · « **Reply #20 on:** September 03, 2019, 07:22 AM »

This whole thread started as a question, but could be seen as a reference or starting point now. For those in need, of course. And if I find new and/or better tooling for working with AsciiDoc, I'll update this thread again.
-Shades (September 01, 2019, 11:30 PM)
Thanks for documenting your experiences - useful! I hope plaintext readable document formats in general get more widely adopted.
-Nod5 (September 03, 2019, 05:50 AM)

I wish CommonMark would take off (or that the creator would let Markdown be standardized)

Lintalist · « **Reply #21 on:** September 03, 2019, 01:06 PM »

Just for reference and AutoHotkey users:

Asciidoctor.ahk: a small GUI app for Asciidoctor users. It will monitor the changes in the .adoc files and create/update .html ones accordingly.

Forum thread: https://www.autohotk....php?f=6&t=67668
Code with instructions: https://github.com/j...n-cj/Asciidoctor.ahk

wraith808 · « **Reply #22 on:** September 03, 2019, 05:03 PM »

I think he's currently using a setup like that, but wanted it in the same UI.