The AsciiDoc Discussion


#1

Hi,

I’m just moving the AsciiDoc discussion from the Slack General room. I’ll just do a unfiltered copy of the comments from that room:

jaredmorgs [6:12 PM]
Hey there everyone. A new member of Write The Docs in Brisbane, Australia.

jaredmorgs [6:12 PM]
I’ve set up an #australia room to see if anyone would like to chat about TechComms in the land downunder. Otherwise I’ll hang here.

jaredmorgs [6:16 PM]
@diogeneshamilton: I’m talking with a .NET dev about using Doxygen to product their API docs. We have a challenge in that we need to get the output into a Confluence server.

jaredmorgs [6:16 PM]
s/product/produce

jaredmorgs [6:17 PM]
The only way I can work out how to do that is to output the docs using the DocBook format, then upload them into Confluence using a DocBook import tool that was created by a Red Hatter.

loisrp [6:18 PM]
You can write in Markdown in doxygen. Does that help with bringing the pages as Markdown to Confluence?

jaredmorgs [6:19 PM]
I’ve already recommended that they use Markdown. Ideally I’d like them to use AsciiDoc

jaredmorgs [6:19 PM]
But Confluence has woeful support for that.

jaredmorgs [6:20 PM]
As does Doxygen. :disappointed:

jaredmorgs [6:23 PM]
What I’m thinking of recommending is that they use a 1:1 relationship between Confluence page node and Class and link between them. Using Confluence as the canonical place. But I’m in two minds about this approach.

Pros

  • it would be easier and wouldn’t involve kludging the tooling to work with confluence
  • it would be well-presented, and would adhere to the specific structure the dev wants

Cons

jaredmorgs [6:23 PM]
*it would separate docs from code

jaredmorgs [6:23 PM]

  • it ‘could’ introduce maintenance issues I’m yet to fully appreciate.

jaredmorgs [6:24 PM]
I’m going to have to head off shortly, but if anyone has any ideas about implementing this with a balance of maintainability vs tooling I’d be keen to hear your thoughts (Pros or Cons).

jaredmorgs [10:19 PM]
hello again everyone. I’ll be here for a few hours more, then it’s back out for the Witching Hour.

swizec [10:54 PM]
how is asciidoc better than markdown?

jaredmorgs [11:27 PM]
AsciiDoc stands out because it supports all the structural elements necessary for drafting articles, technical manuals, books, presentations and prose. It’s capable of meeting even the most advanced publishing requirements and technical semantics. O’Reilly use it as their format of choice for eBooks.

jaredmorgs [11:27 PM]
Another advantage is that it maps directly to DocBook output. There is a AsciiDoc(tor) structure for each DocBook element.

jaredmorgs [11:28 PM]
Stuff that you need to do in HTML in Markdown is natively supported in AsciiDoc (complex tables for example).
:+1:1

swizec [11:30 PM]
well now, that sounds promising

jaredmorgs [11:30 PM]
asciidoctor.org
:eyes:1

swizec [11:30 PM]
I wonder if my favorite markdown-to-ebook converter (leanpub) supports asciidoc

jaredmorgs [11:31 PM]
http://jaredmorgs.github.io/ is a blogging platform (HubPress) that uses AsciiDoc as the writing language.
for Android, Pinball, Open Source, and other interesting topics.

jaredmorgs [11:32 PM]
http://jaredmorgs.github.io/Pinball_Arcade_Users_Guide_Android/ is a user guide written in AsciiDoc and processed using Asciidoctor. It is hosted in GitHub and uses a Travis CI hook to push the HTML up to GitHub Pages.
Android User Guide for FarSight Studio’s The Pinball Arcade

jaredmorgs [11:33 PM]
AsciiDoc has an ePub backend.

jaredmorgs [11:33 PM]
Asciidoctor, I should say.

jaredmorgs [11:33 PM]
AsciiDoc is the markup language. Asciidoctor is the toolchain that processes the AsciiDoc markup.

jaredmorgs [11:35 PM]
http://jaredmorgs.github.io/Asciidoctor_Presentation/ is a reveal.js presentation I created using the reveal.js backend, and hosted on GitHub Pages. There is just so much stuff you can do with AsciiDoc that Markdown just can’t handle.

jaredmorgs [11:36 PM]
Markdown is prolific, but not suited to complex docs that TechComms professionals would be inclined to write.

jaredmorgs [11:36 PM]
I’ve used Markdown and AsciiDoc. It’s AsciiDoc all the way.
:+1:1

jaredmorgs [11:37 PM]
Atom.io make a great editor for Markdown, but it has great support for AsciiDoc. Asciidoctor make a plug-in that lets you live-preview the rendered view (no local tools required)

jaredmorgs [11:39 PM]
I’m having to put up with Markdown support as a compromise in Confluence. Markdown support is better than WYSIWYG. But its not ideal for me.

jaredmorgs [11:40 PM]
The problem with any language other than Wiki markup are not treated as “first class citizens” in Confluence. You need to put the markup inside a Macro, which then renders the text once saved.

jaredmorgs [11:40 PM]
:disappointed:

stiefkind [11:43 PM]
We evaluated AsciiDoc, Markdown and ReStructured Text for use in creating project-based customer documentation. We decided for AsciiDoc, because more flexible, more powerful and more complex documents. Looks like Markdown has a better integrated workflow in Github/Gitlab, though.

kvantomme [11:44 PM]
how does AsciiDoc compare in terms of features against something like DITA? Does it do transclusion and variables and things like that?

jaredmorgs [11:45 PM]
Yeah, it does @stiefkind . The problem with AsciiDoc in GitHub is that it isn’t a whitelisted format in Jekyll. You can write README.adoc files which are rendered in the GitHub editor.

jaredmorgs [11:47 PM]
@kvantomme: That’s a good question, and one that I can’t answer because I haven’t done too much with DITA. It can do variables quite well (which are treated pretty much like DocBook Entities). The native DocBook export is DB 5.


#2

ted-at-cis [9:40 AM]
I write in AsciiDoc for all my docs. I love Asciidoctor’s ability to create a reveal.js slide deck from a text file with one command.

ted-at-cis [9:46 AM]
I use the Asciidoctor browser extension to view all my docs in Chrome. I’ve linked them all together to create a wiki-like intranet site http://tedbergeron.github.io/2015/04/09/AsciiDoc-Website.html or just publish it as HTML with Asciidoctor: http://tedbergeron.github.io/2015/08/16/How-to-Build-a-Website-with-Asciidoctor.html


#3

I"m trying to convert one of our docs from DocBook to AsciiDoc. It’s laborious.

Jared is right, that with the help of the AsciiDoctor project, AsciiDoc does convert to DocBook 5, sort of. (I’ve set up a script with 6 sed commands for a chapter file that I’ve done in AsciiDoc, to complete the conversion.)

O’Reilly does use AsciiDoc – but in its instructions, they set up DocBook snippet templates for commands / output. (Put it in AsciiDoc comments, and the AsciiDoctor tool strips it out.)

The complete approach would be to convert one book at a time – that way I could avoid the sed workarounds.


#4

I’d strongly recommend chatting to Dan Allen (@mojavelinux) on Twitter. If those sed commands are universal, they should be embedded in the code as part of the transformation. Create a bug, or talk to Dan.

For those folks who are stuck in DocBook hell and want to attempt to escape, try https://github.com/opendevise/docbookrx/blob/master/README.adoc

That is very much in alpha phase, but it might help.


#5

Jared, I know Dan :smile:

the sed commands I need are based on my workaround during a transition, since AsciiDoc doesn’t support conversions to DocBook 5 chapters.


#6

Jared, just reread your note, and I did not know about Dan’s Ruby conversion script. It could be quite helpful!

Thanks,
Mike


#7

Hi :smile:

I’m curious what’s your criteria would be to pick between AsciiDoc and Sphinx/RestructredText. I was in a situation where I wanted to start doing high-level developer-focused documentation and basically ended up with either Markdown, Sphinx, or AsciiDoc as option, but eventually went with Sphinx simply because I was already familiar with it and knew how to extend it.

Looking at AsciiDoc back then it kind of appeared more complicated to extend with custom structures and also the split the between the “old” and the “new” toolchain (AsciiDoctor) was worrying me a little bit.


#8

I haven’t heard too much about Sphinx. Could you speak a bit about your experience using it, and why it was right for you?


#9

Just a general heads-up that one of my co-workers just went ahead and created a macro for AsciiDoc (using Asciidoctor) for Confluence.

This is currently the only thing available at the moment that will let you write in AsciiDoc inside a Confluence Macro.

The great thing is that you can use the fantastic Foundation style in all your docs: the macro calls the Foundation CSS and formats your text. This will give any documentation you write on Confluence a distinctive L&F, far superior to the base Confluence L&F.

There is another tool that will supposedly let you push AsciiDoc HTML into Confluence, but it is not working on HTTPS Confluence instances.

This repo hasn’t had any updates in 7 months.


#10

The focus of Sphinx seems to be to make working with a whole set of documents written in RestructuredText easier. It offers macros for easier referencing sections in other documents, a simple search index that can be used offline. As such it implicitly favours multiple mid-size documents instead of a single big one which fits much better with my way of thinking.

It the definitely also helped that Sphinx is written in Python and I’m very familiar with that eco-system.

AsciiDoc kind of looks to me more focused on single larger pages and doesn’t see multiple pages necessarily in a “project” way.


#11

I’m using Sphinx and resTex for a medium size project, an online instructional guide, not a reference. So there’s more prose than tech docs, but there are many small png pics to display along with code examples. I was going to use asciidoc, but I like the way Sphinx lets me use a lot of small files that are indexed automatically. And the html themes are great. The downside is that I like writing with asciidoc better than resTex. It seems more intuitive. Also I don’t need all the Python specific things added by Sphinx, although I can just ignore them. If there was a way to duplicate what Sphinx can do but using asciidoc instead of resTex, I’d switch back. Anyone have any thoughts on that or suggestions?


#12

That does indeed sound interesting.

You’d know about the include:: statements you can use to make your content reusable.

If you have all your documents in one repo, you could implement a strategy to reuse chunks of content pretty easily. The Asciidoctor docs themselves have a pretty advanced referential strategy in place.

Having said all that, it sounds like Sphinx also offers a type of content management functionality as well. There is currently no CMS front end for AsciiDoc that I’m aware of.

I might include @mojavelinux at this point to see if he’s aware of any front ends that allow an atomic approach and reuse opportunity with AsciiDoc.


#13

AsciiDoc is a markup method, for which you can use either the AsciiDoc or Asciidoctor conversion tool. AsciiDoc provides for the creation of large documents with an “include” statement, allowing single documents to be created from separate files. If understand what you’re saying about Sphinx, AsciiDoc does not provide these capabilities - e.g. search index.

AsciiDoc is certainly going ahead in leaps and bounds, but still lacks functionality of other tools like Sphinx. They may be in development as I type.


#14

Are there perhaps some tools around AsciiDoctor that you use for larger projects or what do you use when working with it except for the converter itself? Basically, the only aspect of rST’s syntax that I like is how they handle headings, but everything else looks much nicer in AsciiDoc and I’d really love to give it a “real” try eventually :slight_smile:

Has anyone of you already tried Gitbook’s support for AsciiDoc? That might be a nice alternative to Sphinx if you prefer AD over rST.

P.S.: I’m really sorry that I’ve inadvertently converted this into a Sphinx vs AsciiDoc discussion :pensive:


#15

Speaking of other tools, here’s an example of how I’m testing AsciiDoc.

I’ve set it up with a script using AsciiDoctor / some sed transforms to create a docbook file. Once processed, that content of the original AsciiDoc README.txt file looks like this.

It’s facilitating some single sourcing, where I have a README with the project files, and content in our official documentation.

If you want to test your AsciiDoc skills, I invite you to try out a PR on my README.txt file :slight_smile:


#16

I was just about to tackle another Markdown file in Stash, where I’d rather have AsciiDoc… So I did a little searching and found https://jira.atlassian.com/browse/BSERV-4769, with a prime comment by our very own @jaredmorgs :slight_smile:


#17

Taking the discussion back to pure asciidoc:

I’m still pretty much a n00b at any sort of asciidoctor customization. Anyone here know of an out-of-the-box 3-panel theme (for HTML) for asciidoctor? I’m willing to tackle new frameworks to write it myself, but figured I’d ask first.

many thanks for any guidance/suggestions!


#18

@bradamante As far as generating an HTML website for your AsciiDocs the only thing I can think of to get your 3-panel theme is to use Jekyll. It is a static website generator mostly for blogging, but there are many free themes.

You can use Asciidoctor and the Table of Contents to create two columns. Here’s my tutorial on building a website with Asciidoctor: http://tedbergeron.github.io/2015/08/16/How-to-Build-a-Website-with-Asciidoctor.html

It would probably be easiest to find an HTML template with a 3-panel theme. Then paste your Asciidoctor rendered content into HTML pages by hand.

Then automate that with a script. Here’s mine: https://github.com/tedbergeron/grunt-asciidoctor-assemble … That could give you some clues about taking an HTML template, link to an Asciidoctor stylesheet, add some static content into the side panels. Then paste your Asciidoctor content into the center. There are a couple of templates, but you’ll want to bring your own template.

Also GitBook recently announced they now support AsciiDoc, but it produces a 2-column output.

== Blogging

== Static Website Generators

Asciidoctor has been added to a couple besides Jekyll. I think Awestruck and Gradle. But I don’t know anything about those.

Asciidoctor supports templates; that’s how it generates the Reveal.js slide decks. I’m still looking for ways to build a website with it in the simplest way possible.

Hopefully that gives you some ideas. Sorry I don’t have a clear path for you to follow.


#19

Let me explain further.

I’m new to a team that has fallen in love with Slate, and specifically with the following elements of it:

  • three-column layout
  • single-page HTML
  • cool sticky-element dynamic TOC in the left pane (sorry, not sure how to describe it)

Unfortunately, these criteria seem to be outweighing consideration of the significant limitations of markdown by comparison with asciidoc. But I’m the newest member of the team, so I’m trying to come up with a solution that meets the aforementioned criteria and lets us use asciidoc with as much (seeming) ease as markdown in slate.

At the moment, Ted, your suggestions don’t quite meet my needs :frowning: But I’ll persevere! And thanks for the encouragement.


#20

@bradamante Your quest caused me to look into custom templates for Asciidoctor. So I created this little 3-column demo: http://tedbergeron.github.io/AsciidoctorCustomTemplate/

My source files, if anyone is interested in how this works: https://github.com/tedbergeron/AsciidoctorCustomTemplate

This still doesn’t have everything you are looking for, but I wanted to put it out there with the idea that perhaps the Asciidoctor community could build several custom templates so there would be some options to the default Asciidoctor HTML output.