topbanner_forum
  *

avatar image

Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
  • August 24, 2019, 08:26 AM
  • Proudly celebrating 13 years online.
  • Donate now to become a lifetime supporting member of the site and get a non-expiring license key for all of our programs.
  • donate

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

Shades

  • Member
  • Joined in 2006
  • **
  • Posts: 2,570
    • View Profile
    • Donate to Member
Looking for AsciiDoc editor
« 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

  • Supporting Member
  • Joined in 2006
  • **
  • Posts: 67
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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

  • Supporting Member
  • Joined in 2006
  • **
  • default avatar
  • Posts: 10,186
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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.  :Thmbsup:

jeromg

  • Supporting Member
  • Joined in 2006
  • **
  • Posts: 67
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« Reply #3 on: June 09, 2019, 04:03 PM »
hehe  :Thmbsup:

Shades

  • Member
  • Joined in 2006
  • **
  • Posts: 2,570
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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

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

  • Honorary Member
  • Joined in 2008
  • **
  • Posts: 2,897
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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.

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

  • Member
  • Joined in 2006
  • **
  • Posts: 2,570
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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

  • Honorary Member
  • Joined in 2008
  • **
  • Posts: 2,897
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« Reply #7 on: July 10, 2019, 12:12 AM »
There are no real good AsciiDoc editors, unless you know the syntax by heart.

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

  • Member
  • Joined in 2006
  • **
  • Posts: 2,570
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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

  • Supporting Member
  • Joined in 2006
  • **
  • default avatar
  • Posts: 10,186
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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

  • Member
  • Joined in 2006
  • **
  • Posts: 2,570
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« 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

  • Charter Member
  • Joined in 2006
  • ***
  • Points: 1
  • Posts: 8,793
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« Reply #11 on: July 10, 2019, 08:36 PM »
I'm reminded of this:


ewemoa

  • Honorary Member
  • Joined in 2008
  • **
  • Posts: 2,897
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« Reply #12 on: July 11, 2019, 07:08 PM »
Speaking of standards and specs...

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


Shades

  • Member
  • Joined in 2006
  • **
  • Posts: 2,570
    • View Profile
    • Donate to Member
Re: Looking for AsciiDoc editor
« Reply #13 on: July 11, 2019, 08:32 PM »
Speaking of standards and specs...

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

Sounds like a plan!