Main Area and Open Discussion > General Software Discussion

Looking for AsciiDoc editor

<< < (3/5) > >>

Shades:
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:
I'm reminded of this:


xkcd: Standards

ewemoa:
Speaking of standards and specs...

https://asciidoctor.org/news/2019/01/07/asciidoc-spec-proposal/

Shades:
Speaking of standards and specs...

https://asciidoctor.org/news/2019/01/07/asciidoc-spec-proposal/
-ewemoa (July 11, 2019, 07:08 PM)
--- End quote ---

Sounds like a plan!

Shades:
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.

Navigation

[0] Message Index

[#] Next page

[*] Previous page