S1000D

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

S1000D

rockyallen
Does anyone have any ideas or experience in using Asciidoctor with S1000D, or would be interested in using it?

S100D is a large and complex specification for creating technical publications (https://en.wikipedia.org/wiki/S1000D).
It is normally implemented using expensive commercial packages like Arbortext. The niche I am interested in (as a subsystem supplier) is providing my technical data (currently in asciidoc) to my customer in S1000D format so that they can generate the full equipment documentation.

The tools that I think this would need are:
Asciidoc to data module conversion
Asciidoc to publication module (or publication module to asciidoc) so that asciidoctor can be used to preview the output.

Reply | Threaded
Open this post in threaded view
|

Re: S1000D

mojavelinux
Administrator
@rockallen

I'm not familiar with the S1000D format, but given it's an XML specification, I can say it's the bread and butter of Asciidoctor. Generating it would be very similar to the DocBook (built-in) and Mallard (https://github.com/asciidoctor/asciidoctor-mallard) converters. And converting to formats such as this are the value add of Asciidoctor.

If you need help getting started, don't hesitate to ask. You may also be interested in join the Asciidoctor channel on gitter at https://gitter.im/asciidoctor/asciidoctor.

Cheers,

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: S1000D

kibukj
This post was updated on .
In reply to this post by rockyallen
I would be interested in this for sure. I have only used AsciiDoc and asciidoctor a little bit myself so far, but I am particularly interested in free/open source tools for S1000D. I typically author straight S1000D XML (with some help from some XML plugins for vim) but there's obvious benefits to authoring in a lightweight markup language.

I actually do a lot more of the reverse, S1000D-to-DocBook, to produce Markdown READMEs and manpages for a set of S1000D tools I'm working on. I use an XSLT script for the conversion to DocBook, and Pandoc for everything else.

More relevant is this XSLT script to convert DocBook-to-S1000D, but I haven't spent as much time on it. The original purpose of this was to write content in a lightweight markup language like AsciiDoc, use pandoc to convert it to DocBook, and then to S1000D.

I've been gathering whatever free tools/info I can find related to S1000D here.
Reply | Threaded
Open this post in threaded view
|

Re: S1000D

Lopsotronic
In reply to this post by rockyallen
kibukj, I am honored to be speaking with you "face-to-face". Your work is impressive and is probably the best S1000D-based repo on github.

It's amazing there's more than one of us interested in Asciidoc-S1000D cross-compat, but here we are.

PM me if this forum supports that, I would like to "meet" you in a more personal forum or even in person, geography depending.

Short answer to your question: we need to draft a permissive BREX for adoc that comes as close to stock S1000D SGML as we can get it. It's not out of the question to make "Ascii1000D", much like AsciiRFC project extends Asciidoctor to support RFC7991.

I'm trying to do something very much like what you're describing, using DMCs as filenames, ifdefs for "applicability", and tagged includes for CIRs (Common Information Repositories). If we could adopt "pure" asciidoctor pipelines aka prawn for pdf, textQL would be a gamechanger for parts information repositories, but the prawn PDFs . . ah well, see below.

The weak link is writers, who aren't familiar with git or version control or anything like that, at all. They're hitting the same file from different branches and getting angry about conflicts on the merge.

They're also needing more PDF customization than prawn can give them, but don't have the XSL chops to really customize the fopub docbook stack on their own. PDF customization eats a ton of my time.

At the end of the day this implementation will probably die, but this specific method is for sure going to be the way I do my next publications environment. It's just too damn efficient . . assuming you have a staff of writers who know how to git.
Reply | Threaded
Open this post in threaded view
|

Re: S1000D

kibukj
In reply to this post by rockyallen
Lopsotronic, thank you! I'm flattered you think it's impressive.

I've started a very bare-minimum Asciidoctor converter for S1000D:
https://github.com/kibook/Asciidoctor-S1000D-converter
Not much is handled yet, but I think this will at least be a better approach than the Asciidoc -> Docbook -> S1000D pipeline I've used in the past.

However, as Lopsotronic pointed out, the next step would be an extension to Asciidoc, since there are many things that don't necessarily map to Docbook/Asciidoc elements. The base Asciidoc syntax will probably only accommodate most of the descriptive (descript.xsd) and some of the procedural (proced.xsd) S1000D schemas.

Personally, I think my focus will still be on writing in XML, but I like the idea of "Ascii1000D".