Page 1 of 1

Single-sourcing with PDF and xml file outputs

PostPosted: Fri Feb 19, 2021 9:31 am
by bwofficer
I want to single-source error message and corrective actions text for some industrial equipment to ensure they appear identically in:
1. The user manual (PDF)
2. The diagnostics manual (PDF)
3. Online help
4. The on-screen text file (probably xml) which will be given to a software engineer to incorporate into the machine control panel software

No. 4 is where I'm getting stuck. The software engineer expects a text file listing all the errors by code number, title, description, causes list, and corrective actions list, using xml tagging or similar.

I either need to get Flare to manage the text, creating the PDFs and help site as normal but ALSO outputting the text tagged in a custom way that his software can read. OR I can create the xml file using some other xml editor using only tags that the software engineer expects then somehow map those elements to snippets or tables in Flare. It depends which is easier - to consider the software-oriented text file as the master and import/map it onto parts of my Flare documents, or to consider the text in Flare as the master and somehow output it reformatted as a tagged text / xml output.

The structure for the xml file isn't defined, but it would look something like the following. Please pardon that it's not good xml. I'm a complete xml novice (as well as being a relatively new Flare user).

<edescription>The primary arm of the doodah inhibitor has jammed in the on position</edescription>
<ecause>Primary arm joint seized</ecause>
<ecorrective>Grease the primary arm joint</ecause>
<ecause>Thingimjig trapped in primary arm mechanism</ecause>
<ecorrective>Using a trusty baseball bat, forceably remove any thingimjigs trapped in the primary arm mechanism</ecause>

Any ideas how to proceed?

Re: Single-sourcing with PDF and xml file outputs

PostPosted: Sun Feb 21, 2021 3:45 pm
by doloremipsum
It's not a full solution, but have you looked at the Clean XHTML output? It strips away any non-standard Flare formatting, doesn't attach a skin, etc. Just basic XHTML pages.

You probably can't write the custom XML directly in Flare (or I guess you could, but it obviously can't be used for your other outputs). My instinct would be to write it like this:
Code: Select all
<p class="ecode">E206</p>
<p class="etitle">DOODAH INHIBITOR JAMMED ON</p>

Then after you build your clean XHTML, you give it to the developer and they write a program that replaces your paragraphs with their special XML (I'm not a programmer, but I suspect this is very easy).

Re: Single-sourcing with PDF and xml file outputs

PostPosted: Mon Feb 22, 2021 1:24 am
by Dave Lee
Why not provide it in HTML format?

You just need to use consistent tags for the data; e.g.
<p class="ecode">E206</p>
<p class="etitle">Doodah</p>

The developer should be able to read content in that format.

If you need the data in a single file, and it isn't a single file in your help, then maybe have the data for each item in a snippet and put all the snippets in a single topic.
You could also build a target specifically for the developer, using Clean XHTML format.

Re: Single-sourcing with PDF and xml file outputs

PostPosted: Wed Feb 24, 2021 9:34 am
by bwofficer
Thanks, Dave and Doloremipsum

I'll give that a go.

One potential problem is that the diagnostic help information is presented as tables in the user manual and diagnostic manual. Simply outputting that as an additional clean HTML target means I'd have to make sure the table is laid out in a way that puts the information in the right order when the programmer comes to reads it in.

It's further complicated by the tables being laid out differently between the user manual and the diagnostic manual. In the diagnostic manual there will eventually be one table for each error code, the table containing a fair bit of extra information. The user manual just has a single diagnostics help table, with the bare minimum of info about each error (the code, the message/title, and the single-sentence description that expands on the message a little). Even just creating a single-source file for both is proving messy. With the diagnostics manual treating each error as a topic, but the user manual bundling them all into one topic, I can't see an easy way to structure the source to compile into a one-topic table for one manual and a topic per error for the other. With no overarching super-topic I have to do the reuse at snippet level and end up with several hundred snippets.

Maybe I should approach it from the other direction and consider an external (to Flare) XML tree representation of the error info as the editable master, laying that out in a way the machine programmer can work with, and importing it into Flare when I need to (maybe by means of XSLT).