Ideas for an Asciidoctor Editor / IDE

This based on a month of intensive work with Asciidoctor by an old hand at tech documentation and software engineering, but a complete newcomer to Asciidoctor (so apologies to the long-timers for any repeats):

* Let's say the starting point is the Brackets editor (which already has a simple Asciidoc plug-in). This is attractive, because you can open a directory not just files. I have a parent directory under which 9 specifications live; each of those has average 7 .adoc files. That's 63 files (plus another hundred or so image files I can see) I can get to, and do search and replace on. Brilliant.

* Now I select a file from the left-hand file menu in Brackets. In the main pane I see some adoc source. But what I would like to have is another left-side (probably below the file system tree) outline tree showing the heading structure 'comb', plus includes, image  lines. If it were really smart, and it realised that a bunch of .adoc files in one directory were a single logical doc (or book), then it could compute the heading numbering, and I could easily find section 9.4.12 that someone reported from the web-visible document as being problematic. (Keeping this update live as I work on the docs might be interesting:).

* I also want the Xrefs extracted from the doc and shown in the left, either in the doc outline tree or below it. If I click on one of these, the target document is brought up in a second doc pane, horizontally separated from the main content pane. The editor would know about these due to having analysed the entire doc include structure, and scanned all docs for items in [bibiography] sections.

* Xref analysis - If  I click on a reference in a biblio section (or right-click or whatever), a search is run on the opened directory (as Brackets does now) and the results shown in another horizontal split pane below (I think there should be a dedicated Search and replace batch pane generally).

I also want to be able to change the tag of a reference (what is in the [[[]]]) and have it update all files containing citations of that reference.

I also want a way to see all internal Xrefs in source docs that appear to have no target.

* Xref code-completion. During editing if I start typing '<<xxx>>' I get a drop-down list of possible Xref targets to choose from.

* Bibliography Management. As noted elsewhere a nice integration of bib-tex into Asciidoctor would fix this. Practically, it might be the case that the [bibliography] sections were in fact bib-tex files, and some intermediate generation was being done on the fly to get the correct .adoc content. When I have played with the asciidoc-bib tools, I'll know more.

* Smart include / image macro creation. I want to be in a document and do some operation to create a new 'include' or 'image' line by selecting another file in the file tree.

* Smart macro building I want to be able to hover or click on a macro and get some kind of popup showing settable options (e.g. things like image 'align'). Multi-value settings should be shown as drop-downs.

* Having a live HTML preview pane is useful (as the current Asciidoctor plugin does), but it needs to be detachable to be on another screen. I don't use the current AD plug-in, because having a browser window opened on the 2nd screen and a bash shell to rerun the build command are more useful to me.

Note, live preview, to be done properly needs a way for the build command line to be specified, because it may contain (as I do) switches setting Adoc variables, and other options needed for proper generation.

* A Table Editor for non-trivial tables.

That's it for now. Is there an Editor / IDE wishlist somewhere to pin this to?

I should say at this point that even with none of the above in place, it's still amazingly (to me) efficient, comparatively, to manage and build documents in the current Brackets/Asciidoctor environment. I come from using FrameMaker for 20y for large tech docs, and I can say that the only major thing Frame wins on is managing Xrefs properly. But Asciidoctor wins hands-down on being able to build big docs from multiple sources & inclusions, and it's easily comparable on the multi-channel output as well (well, when the PDF output is working properly, it will be ;-)

For interest, here is a snapshot of how I name and view docs in Brackets.

Take a look at AsciidocFX, it has much of what you're looking for. 

On Wednesday, July 22, 2015, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:

This based on a month of intensive work with Asciidoctor by an old hand at tech documentation and software engineering, but a complete newcomer to Asciidoctor (so apologies to the long-timers for any repeats):

* Let's say the starting point is the Brackets editor (which already has a simple Asciidoc plug-in). This is attractive, because you can open a directory not just files. I have a parent directory under which 9 specifications live; each of those has average 7 .adoc files. That's 63 files (plus another hundred or so image files I can see) I can get to, and do search and replace on. Brilliant.

* Now I select a file from the left-hand file menu in Brackets. In the main pane I see some adoc source. But what I would like to have is another left-side (probably below the file system tree) outline tree showing the heading structure 'comb', plus includes, image  lines. If it were really smart, and it realised that a bunch of .adoc files in one directory were a single logical doc (or book), then it could compute the heading numbering, and I could easily find section 9.4.12 that someone reported from the web-visible document as being problematic. (Keeping this update live as I work on the docs might be interesting:).

* I also want the Xrefs extracted from the doc and shown in the left, either in the doc outline tree or below it. If I click on one of these, the target document is brought up in a second doc pane, horizontally separated from the main content pane. The editor would know about these due to having analysed the entire doc include structure, and scanned all docs for items in [bibiography] sections.

* Xref analysis - If  I click on a reference in a biblio section (or right-click or whatever), a search is run on the opened directory (as Brackets does now) and the results shown in another horizontal split pane below (I think there should be a dedicated Search and replace batch pane generally).

I also want to be able to change the tag of a reference (what is in the [[[]]]) and have it update all files containing citations of that reference.

I also want a way to see all internal Xrefs in source docs that appear to have no target.

* Xref code-completion. During editing if I start typing '<<xxx>>' I get a drop-down list of possible Xref targets to choose from.

* Bibliography Management. As noted elsewhere a nice integration of bib-tex into Asciidoctor would fix this. Practically, it might be the case that the [bibliography] sections were in fact bib-tex files, and some intermediate generation was being done on the fly to get the correct .adoc content. When I have played with the asciidoc-bib tools, I'll know more.

* Smart include / image macro creation. I want to be in a document and do some operation to create a new 'include' or 'image' line by selecting another file in the file tree.

* Smart macro building I want to be able to hover or click on a macro and get some kind of popup showing settable options (e.g. things like image 'align'). Multi-value settings should be shown as drop-downs.

* Having a live HTML preview pane is useful (as the current Asciidoctor plugin does), but it needs to be detachable to be on another screen. I don't use the current AD plug-in, because having a browser window opened on the 2nd screen and a bash shell to rerun the build command are more useful to me.

Note, live preview, to be done properly needs a way for the build command line to be specified, because it may contain (as I do) switches setting Adoc variables, and other options needed for proper generation.

That's it for now. Is there an Editor / IDE wishlist somewhere to pin this to?

I should say at this point that even with none of the above in place, it's still amazingly (to me) efficient, comparatively, to manage and build documents in the current Brackets/Asciidoctor environment. I come from using FrameMaker for 20y for large tech docs, and I can say that the only major thing Frame wins on is managing Xrefs properly. But Asciidoctor wins hands-down on being able to build big docs from multiple sources & inclusions, and it's easily comparable on the multi-channel output as well (well, when the PDF output is working properly, it will be ;-)

For interest, here is a snapshot of how I name and view docs in Brackets.

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Ideas-for-an-Asciidoctor-Editor-IDE-tp3542.html

To start a new topic under Asciidoctor :: Discussion, email <a href="javascript:_e(%7B%7D,&#39;cvml&#39;,&#39;ml-node%2Bs49171n1h37@n6.nabble.com&#39;);" target="_blank">ml-node+s49171n1h37@...
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--
Sent from Gmail Mobile

> * Having a live HTML preview pane is useful (as the current Asciidoctor plugin does), but it needs to be detachable to be on another screen. I don't use the current AD plug-in, because having a browser window opened on the 2nd screen and a bash shell to rerun the build command are more useful to me.

The current Asciidoctor plugin has a detachable preview pane and I love it!:)
There's an icon for that on the preview pane.

It does indeed - which is good. However, I notice two things:

1. it leaves a persistent .html file in the work directory. If not vigilant, I may end up pushing this up into Github or wherever, when it is really a junk file (in my case, it corresponds just to one chapter; the HTML file I want to control is for the whole book).

I would suggest that these preview files should be in a /tmp (c:\temp) or similar area.

2. It doesn't render code correctly - probably because it doesn't see the directives in the master file that includes the chapter file? So I suspect it doesn't know I'm using Pygments, which means it probably assumes something else for which there is no colouriser for the language I am working on. So preview mode is no use when I am working on a serious section of document that has a lot of code I want colourised properly.

Obviously these issues could be fixed pretty easily.

Does it make sense to have an informal standard for setting up Asciidoc books to help tools like Brackets figure out what to do? E.g. I am using file names like

master.adoc
master01-chapter1.adoc
etc
masterAppA.adoc

with the master.adoc including the other files.

wolandscat wrote

Does it make sense to have an informal standard for setting up Asciidoc books to help tools like Brackets figure out what to do? E.g. I am using file names like

master.adoc
master01-chapter1.adoc
etc
masterAppA.adoc

with the master.adoc including the other files.

I think that makes sense. There needs to be some standard in order to hook things together.

GitBook does that. README.md becomes the index.html and SUMMARY.md becomes the Table of Contents links in a sidebar

LightGuardjp wrote

Take a look at AsciidocFX, it has much of what you're looking for.

I haven't installed it, but going by the online documentation, it doesn't seem to address anything in the Xref area, which for me is probably the key thing. Or does it, and it's just not mentioned?

This is an awesome read with a lot of insights. Just to understand the preference, would you prefer a local install typically over something web-based?

I'm fine with local installs. I use Thunderbird, Chrome, and other tools. As long as a local install either knows how to update itself, or can very easily be updated e.g. by running some simple 'update' script, it's fine.

Purely web side tools bring all their own difficulties.

I saw this in my twitter feed Say hello to our new Markdown toolbar (video).

Having buttons for "Bold", "Italic", "create a link", "insert an image" is definitivelly something I would like to have in a AsciiDoc IDE.

In my opinion those should work more like in Microsoft word: the buttons needs to be toogle buttons:
If the carret is inside a bold bloc: "some *important|* text" then the bold button should be enabled and a click on this button remove the bloc: "some important| text".

I am a little bit lost about the process. Should we collect the ideas here or on the wiki page:
https://github.com/asciidoctor/asciidoctor/wiki/AsciiDoc-Tooling:-Requirements-and-Ideas

As a tech writer who has also used Framemaker, as well as Interleaf/Quicksilver, Ventura, etc, I too have been really impressed with Asciidoctor and what it can do.

I edit my files in vim with the VOom plugin that supports a folded window of you Asciidoc files (among other formats).

I also use Asciidoctorfx to preview and create pdf's.

Good to know there are others like us out there!


Russ

On 04/02/2016 16:10, russurquhart1 [via Asciidoctor :: Discussion] wrote:
> As a tech writer who has also used Framemaker, as well as Interleaf/Quicksilver, Ventura, etc, I too have been really impressed with Asciidoctor and what it can do.
>
> I edit my files in vim with the VOom plugin that supports a folded window of you Asciidoc files (among other formats).

I'm a vim user too (vi for 30 years ;-) but I have to say I only do quick edits on Asciidoc files with vim now; any serious editing session I do in brackets, which knows Asciidoc syntax. Others tell me AsciidocFX is a good tool as well.

But I must hunt down that vim plug-in and try it.

>
> I also use Asciidoctorfx to preview and create pdf's.

ah - interesting - I'd be interested to know your experiences. We gave up on PDFs for the moment, waiting until next release, because there are too many things we need that are not there yet (I know the team is working hard on that).

>
> Good to know there are others like us out there!
>
>
> Russ
>
> If you reply to this email, your message will be added to the discussion below:
> http://discuss.asciidoctor.org/Ideas-for-an-Asciidoctor-Editor-IDE-tp3542p4265.html
> To unsubscribe from Ideas for an Asciidoctor Editor / IDE, click here.
> NAML


--
Thomas Beale
Management Board, Specifications Program Lead, openEHR Foundation
Chief Technology Officer, Ocean Informatics
Chartered IT Professional Fellow, BCS, British Computer Society
Health IT blog Culture blog

My opinion on this topic is. An IDE support is important for such project like asciidoctor.

I use asciidoctor for technical writing. For example paper or thesis. And I use two main formats: HTML and PDF
Minimal set of features that I think are essential is:
Outline: just for first two heading levels would be pretty
One File: everething is in one file because of outline feature :). Editor should handle big files easily.
Syntax highliting:
Preview in separate window:
asciidoctor-pdf on mouse click:

My subjective experience with some editors:

Brackets
Pros:
One File: powerfull enough
Syntax highliting: the best of the best
Preview in separate window: good, supports also browser preview

Cons:
Outline: not supported
asciidoctor-pdf on mouse click: not supported
Autocomplete code: not found

Atom
Pros:
One File: laggy a little bit
Autocomplete code: the best autocomplition plugin

Cons:
Outline: may be supported in future
Syntax highliting: some highlithing
Preview in separate window: both plugins failed to install
asciidoctor-pdf on mouse click: not supported

Sublime Text 3
Pros:
One File: very fast editing
Syntax highliting: could be like in Brakets
Preview in separate window: on Ctrl-Alt-o in browser. Works very well

Cons:
Outline: not supported
asciidoctor-pdf on mouse click: not supported
Autocomplete code: no

IntelliJ
Pros:
Outline: Yes. It is a little bit buggy but it works.
One File: Very fast editing
Syntax highliting: could be like in Brakets
Autocomplete code: works well

Cons:
Preview in separate window: Works well in a separate tab but not in extra window
asciidoctor-pdf on mouse click:

AsciidoctorFX
Pros:
Outline: Yes.
One File: Ok
Syntax highliting: Could be like in Brakets :)
asciidoctor-pdf on mouse click: Yes
Autocomplete code: is ok

Cons:
Preview in separate window: only tab
Has problems with custom asciidoctor header

Notepad++
Cons:
Syntax highlighting: is buggy

I prefer Brakets and Sublime Text 3 editors for now.

Would be good to provide a matrix for editor features what is supported and
what not. And place it in a findable place maybe getting started. I
invested a lot of time to find a suitable editor.
As example

Line soft wrapping Feature:
Brakets : Atom : IntelliJ
yes : yes : no

By now I am using Brakets but I don't like that this editor is from Adobe ...

Here is what I get for example when I try to install asciidoctor preview in atom.
Installing “asciidoc-preview@0.6.0” failed.Hide output…
Failed to install asciidoc-preview because Git was not found.
The asciidoc-preview package has module dependencies that cannot be installed without Git.
You need to install Git and add it to your path environment variable in order to install this package.
You can install Git by downloading, installing, and launching GitHub for Windows: https://windows.github.com
Run apm -v after installing Git to see what version has been detected.
I tested also Eclipse plugin from your link https://github.com/asciidoctor/asciidoctor/wiki/AsciiDoc-Tooling:-Requirements-and-Ideas#references

Eclipse:
Good working Outline.
Codefolding is really nice feature.
 But that plugin don't support asciidoctor it supports asciidoc in preview tab.