How to create a custom backend

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

How to create a custom backend

elygre
I wonder how I best go along creating a custom backend? What examples should I look at, is there a presentation or some documentation, etc?

My use case is this: In a documentation set, I need to generate separate HTML-pages for certain tables, to use as on-line help, e.g.:

* The system has two forms "userform" and "groupform"
* The documentation has sections describing these forms, and others
* For each of these forms, there is a table some labelled as "helptable,userform" and "helptable,groupform" (or the like)
* For each "helptable" in the asciidoctor source, generate a separate html-file "userform-help.html" and "groupform-help.html", containing only these forms.

We already generate all this from another format, so the only thing I need to know (I think!) is how to create a new backend :-)

Eirik
Reply | Threaded
Open this post in threaded view
|

Re: How to create a custom backend

mojavelinux
Administrator
Eirik,

I'll start by saying that I'm well aware we need better documentation for how to create custom backends. When I finally get a chance to focus on writing, it's near the top of the list.

Fortunately, there are lots of developers playing around with backends, so we have no shortage of good examples.

You can start by reading the README in the asciidoctor-backends repository, which was recently updated by Brian Street. Feedback is welcome if you have ideas about how to improve the docs.

https://github.com/asciidoctor/asciidoctor-backends/blob/master/README.adoc

The asciidoctor-backends repository is a collection of template-based converters. There is one template file per node (though you can structure it however you'd like). If a template file is missing for a node, Asciidoctor falls back to the built-in handler for that node, so you only have to implement templates for nodes you want to customize.

We maintain a complete set of templates for the built-in converters here:

(Thanks to Jakub for creating a test suite to ensure these are up to date).

The downside of the template-based converters is that it doesn't give you control to write multiple files from a single AsciiDoc document. Instead, you are merely customizing the sections of the single file that is generated by default.

If you want to produce multiple files from a single input file, then you need to implement a custom Ruby-based converter. There's almost no limit to what you can do once you create a custom converter in Ruby, though there are far less examples for doing so.

I have put together a gist that demonstrates a proof of concept for creating chunked HTML output. That should give you some ideas about how to create pages for certain tables.

https://gist.github.com/mojavelinux/d94372393950ca76d594

What you'll actually do is create a convert that implements the Writer interface. The Writer interface allows you to control when files are written to disk, which is when you can produce multiple files. I would start by playing around with that gist and see how far you get. If you have questions, feel free to ask. Your use case could certainly help me with knowing how to write the docs for it.

It is possible to combine a Ruby-based converter with a template-based converter, though that's probably a more advanced topic ;)

In the end, I want you to think of an AsciiDoc document as a flat database of content. From it, you can produce one file or many. The goal of the converter and extension APIs is to allow you to produce exactly what you want to produce. In other words, a total separation of content and presentation / publishing.

Cheers!

-Dan

On Mon, Dec 1, 2014 at 3:35 AM, elygre [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I wonder how I best go along creating a custom backend? What examples should I look at, is there a presentation or some documentation, etc?

My use case is this: In a documentation set, I need to generate separate HTML-pages for certain tables, to use as on-line help, e.g.:

* The system has two forms "userform" and "groupform"
* The documentation has sections describing these forms, and others
* For each of these forms, there is a table some labelled as "helptable,userform" and "helptable,groupform" (or the like)
* For each "helptable" in the asciidoctor source, generate a separate html-file "userform-help.html" and "groupform-help.html", containing only these forms.

We already generate all this from another format, so the only thing I need to know (I think!) is how to create a new backend :-)

Eirik


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-create-a-custom-backend-tp2494.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--