A while ago I blogged on why we replaced FrameMaker with Asciidoctor for the technical publishing function of openEHR.org. At around that time I posted on an Asciidoctor mailing list my wishlist for Asciidoctor. I reproduce that list here. As another poster mentioned, some of this is in a tool called AsciidocFx, but a fair bit isn’t as well, so to date, I have not switched to it.

My 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 an Xref (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 completion. 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.

I should point out that our previous tool, FrameMaker didn’t do most of this; I don’t know if any tool does. But I think it’s the future of technical document production.