Transform the DITA document into DocBook.<\/strong><\/p>\nAll the toolkit’s transformations involve running an Ant script:<\/p>\n
ant options<\/var> targets<\/var><\/code><\/pre>\nTo transform DITA to Docbook, run:<\/p>\n
ant -Dargs.input=path<\/var>\/toc.ditamap dita2docbook<\/code><\/pre>\nIf the transform fails (and all your environment variables are set correctly), there might be errors lurking in your generated DITA source. This is AuthorIT’s way of telling you, “Don’t let the door hit you on the way out, jerk!”<\/p>\n
\n- If DITA-OT complains about a missing topic reference, there’s a good chance
toc.ditamap<\/code> is referencing a topic that doesn’t exist. Go back to the original AuthorIT doc and try to identify the missing topic. If all else fails, delete the reference from toc.ditamap<\/code> and move on. Your readers already knew about the safety hazards of handling lithium deuteride, anyway.<\/li>\n- If a topic contains a
xref<\/code> with a crazy relative path, this can really confuse DITA-OT. The good news is that the toolkit indicates the path that is causing the problem. The bad news is that AuthorIT dumps its DITA output in UTF-16, which is really annoying to grep<\/code> through. <\/li>\n- If you had any “Note” paragraph styles in your AuthorIT doc, these might disappear. Even more strangely, “Warning” paragraphs do make it through.<\/li>\n<\/ul>\n<\/li>\n
- \n
Clean up the DocBook output with a script.<\/strong><\/p>\nCongratulations, your document is now DocBook! Well, more accurately, it’s “DocBook”. Just be happy your tables made it through, sort of.<\/p>\n
Fortunately, you can fix many issues pretty easily by running the document through a cleanup script. This script is particularly important if you’re converting multiple documents. The canonical language for the script is XSLT, but if you’d rather stick it to the W3C Man<\/em>, Python or Perl would work fine too. Here’s what you’ll want to fix:<\/p>\n\n- Remove all
id<\/code> attributes. These generated IDs are duplicated throughout the doc, and nothing points to them. Throw them away and start over.<\/li>\n- Remove all
remap<\/code> attributes. In theory, these attributes contain useful information about the original DITA element, which in turn could help you design your post-processing script to provide better-quality DocBook markup. In practice… eh, not so much.<\/li>\n- Remove all
sectioninfo<\/code> elements. They’re often invalid, and always contain nothing useful.<\/li>\n- Remove empty
type<\/code> attributes. Not sure how those got there.<\/li>\n- Remove empty
para<\/code> elements.<\/li>\n- Change
sidebar<\/code> elements to section<\/code> elements. Like the empty type<\/code> attributes, these are another mystery guest.<\/li>\n- Join
programlisting<\/code> elements. If you had any multi-line code samples, you might find that in the transformed DocBook, each line appears in its own programlisting<\/code>. Join adjacent programlisting<\/code> elements into a single programlisting<\/code> (or screen<\/code>, if appropriate).<\/li>\n- (Optional) Change the
article<\/code> to a book<\/code>, if appropriate. Add chapter<\/code> elements as necessary.<\/li>\n- (Optional) Try to improve the quality of the markup by changing
emphasis role=\"bold\"<\/code> and literal<\/code> elements to something more specific. For example, you define a list of commands that appear in your book and wrap each one in a command<\/code> element. Creating explicit lists of commands, GUI buttons, and so on is tedious, but it’s still better to do these substitutions in the script.<\/li>\n<\/ul>\nFinally, there’s the issue of broken IDs and links. Currently, every one of your AuthorIT hyperlinks is now a ulink<\/code> that falls into one of these categories:<\/p>\n\n- The
ulink<\/code>‘s url<\/code> starts with “mailto:<\/code>“. Convert these to email<\/code> elements.<\/li>\n- The
ulink<\/code>‘s url<\/code> starts with “http:\/\/<\/code>“, or “ftp:\/\/<\/code>“, or “gopher:\/\/<\/code>“. Leave these alone.<\/li>\n- The
ulink<\/code>‘s url<\/code> points to something like “D1228.xml<\/code>“, a.k.a. nowhere. These are your former internal hyperlinks. They’re all broken.<\/li>\n<\/ul>\nBut don’t be discouraged, your script can actually “guess” at where many of these links should point. If a given internal ulink<\/code> contains something like, “Configuring the MIRV Launch Sequence”, there’s an excellent<\/em> chance that somewhere else in your document there’s a section<\/code> with a title<\/code>, “Configuring the MIRV Launch Sequence”! So all you have to do is:<\/p>\n\n- Convert the content of each
ulink<\/code> to a nicely-formatted ID. Replace whitespace with underscores, remove extraneous punctuation, and lower-casing everything.<\/li>\n- Convert the
ulink<\/code> to an xref<\/code>, setting the linkend<\/code> to the new ID.<\/li>\n- For each
section<\/code> element, apply the same ID-conversion algorithm to the section<\/code>‘s title<\/code>. Set this value as the section<\/code>‘s id<\/code>.<\/li>\n<\/ol>\nA healthy fraction of your id<\/code>s and linkend<\/code>s should now match up, fixing those broken links.<\/p>\n<\/li>\n- \n
Clean up the DocBook output manually.<\/strong><\/p>\nOh, you’re not done yet! Here’s a non-exhaustive list of what’s left:<\/p>\n
\n- Fix the remaining invalid
id<\/code>s and broken links that your script didn’t catch.<\/li>\n- Fix any other DocBook validity issues.<\/li>\n
- Add
programlisting<\/code> and screen<\/code> elements where appropriate. Remove excess carriage returns as necessary.<\/li>\n- Make your inline markup consistent. For example, all command-line tools should be consistently marked up as
command<\/code>s (assuming your organization chooses to use that element). You can partly script this, but mostly this is a manual job.<\/li>\n- Remove any mysterious duplicate
section<\/code>s.<\/li>\n- Rename your images from “
898.png<\/code>” to something more descriptive, such as “mirv_reentry_trajectory.png<\/code>“. Embed the images in a figure<\/code> with a proper title<\/code> and id<\/code>.<\/li>\n- Add any missing front matter.<\/li>\n
- Rebuild your index by hand. By hand<\/em>. Jesus H. Christ.<\/li>\n<\/ul>\n
Now put your feet up on the desk and pour yourself a well-deserved gin-and-tonic. If anyone asks you why you look so frazzled, do not<\/em> under any circumstances tell the truth. Otherwise they’ll just respond with, “Well, why don’t you just move it all to the corporate wiki?” And there’s only one rational reaction to that<\/em>. Don’t get me wrong, it’s not easy to inflict serious blunt force trauma using a 15″ Powerbook, but somehow, you’ll find a way.<\/p>\n<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"Congratulations, your document is now DocBook! Well, more accurately, it’s “DocBook”. Just be happy your tables made it through, sort of.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[11,2],"tags":[],"class_list":["post-314","post","type-post","status-publish","format-standard","hentry","category-howto","category-tech"],"_links":{"self":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts\/314","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/comments?post=314"}],"version-history":[{"count":0,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/posts\/314\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/media?parent=314"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/categories?post=314"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.goer.org\/Journal\/wp-json\/wp\/v2\/tags?post=314"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}