Main Area and Open Discussion > General Software Discussion
Looking for AsciiDoc editor
ewemoa:
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)
--- End quote ---
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/asciidoctor/asciidoctor-vscode
https://github.com/bcherny/better-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:
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:
There are no real good AsciiDoc editors, unless you know the syntax by heart.
-Shades (July 09, 2019, 11:37 AM)
--- End quote ---
As an Asciidoc newbie, I surely don't. Here's one thing I found tricky to figure out:
https://mrhaki.blogspot.com/2017/10/awesome-asciidoctor-use-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,
--- End quote ---
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.
--- End quote ---
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.
--- End quote ---
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).
--- End quote ---
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".
--- End quote ---
Perhaps someday something better will show up at:
https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
Shades:
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:
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.
Navigation
[0] Message Index
[#] Next page
[*] Previous page
Go to full version