Documenting XML in DITA 1.3

We have XML configurations in some Wind River software, so we need to document those XML elements and attributes. When we document our DITA implementation for our writing team, we also mention XML elements and attributes. Here are my thoughts on our transition process, and on XML domains in DITA.

I am looking forward to replacing the DITA 4 Publisher’s XML domain with DITA 1.3’s XML Mention Domain. I think the only difference is that <xmlelem> becomes <xmlelement>. We will have to allow the old element “forever” since it is found in topics in our CMS, including tagged copies of our releases.

We are using Schematron to enforce rules in the oXygen editor, so we will likely use that to ask writers to change instances of <xmlelem> to <xmlelement> when they edit a topic containing the old element.

Also, we mention the names of our doctypes. We consider doctypes to be different from regular XML elements, so <xmlelement> is not suitable. We use (writing from home here – guessing the correct spelling) <doctype-name>.

Does anyone else mention the name of XML Doctypes in your documentation? Do you use <xmlelement>? What do you do instead?



Choosing a version control system for your Tech Pubs department

I assume here that you have already identified a need for a version control system. Choosing one may be your next step.

First choice: Use whatever version control system your developers use.

  • Your department may have to pay for a license on the server software, but you will have advice and assistance readily available.
  • Some of your writers will use it for different tech pubs projects and get proficient at a tool that is crucial to your company’s developers.
  • You may be able to piggyback your server license on theirs.
  • The IT department that set up their server for version control already knows how to do that. When you get your own server, they will already know how to set it up.

Second choice: Git

  • This is one of the most popular open source version control systems.
    Even if your company does not use it, you should be able to find help and advice in your development team. Check that this is true at your company before you make a decision.
  • Like most version control systems, there are GUI tools for Git, so you are not restricted to command line access to your data. On Windows, TortoiseGit is good, easy to use, and free.
  • Several companies provide commercial servers for Git, including Atlassian. Atlassian’s BitBucket server is inexpensive, but full-featured and easy to use and administer.
    There are open source servers for Git.

Other considerations:

  • Pay extra, if necessary, to keep your data in a separate storage area from the developer’s data. This storage area is usually called a repository, which is abbreviated repo.

PDF.js ticket #4469

I filed a bug against the default PDF viewer in Firefox 27.0.1, called PDF.js.

It won’t display text in Palatino font.

I am writing this blog as a place to store an example PDF file that displays the problem.



Using Image Magick to shrink your JPGs

Here is a small script to use Image Magick tools on the JPEG files from your camera, and create “smaller” versions in a new sub-folder called “smaller”.

It must be changed to match the JPG files produced by your camera. It looks for JPEG files with specific dimensions.

And of course this version only works on Unix-like systems that have the “bash” shell available.

rm -f list.txt
mkdir smaller

echo List of JPG files
for a in P*.JPG; do (identify $a >>list.txt); done

echo convert 4032x2272 images
for a in $(grep -e "2272" list.txt | sed -re "s/^([^ ]+).*/\1/"); do (convert $a -comment "Copyright Robert Echlin. Larger version available." -resize 1920x1080 smaller/$a ); done

echo convert 4032x3024 images
for a in $(grep -e "3024" list.txt | sed -re "s/^([^ ]+).*/\1/"); do (convert $a -comment "Copyright Robert Echlin. Larger version available." -resize 1600x1200 smaller/$a ); done

echo checking ...
echo Local files
ls *JPG | wc -l

echo smaller files
ls smaller | wc -l

Editing menus on LXDE

The menus are created from the foo.desktop file for each application.

To find them, you can do a couple of things.

First, using Synaptic package manager, select the package, then click on the “Properites” icon in the toolbar. Use the tab “Installed Files”.

Second, you can use this command line, where the “package-name” needs to be the name of your package. Tab completion works for Bash shell on the name of the package, if you know how it starts.

dpkg -L package-name | grep desktop

I found this out because I needed to change the “EXEC” string in “d2x-rebirth-demo” (the “Descent 2” rewrite) to:

/usr/local/games/d2x-rebirth/d2x-rebirth -hogdir /usr/local/games/d2x-rebirth/data

Proposed Stack Eschange site for DITA

Anders Svensson has created a proposal for a DITA Stack Exhange Site.
It’s at

DITA is an OASIS standard for XML documentation.

User Group Connect has a new URL

“User Group Connect 2013” has a new URL. You can find us at

If you don’t know about UGC, it is an opportunity for User Group’s in Ottawa to get together and for the Ottawa technology community to get together to meet some of the 30 or so User Groups in Ottawa.

On Saturday February 9, from 10am to 4pm, join us in the lounge at Shopify, 126 York St. The entrance is at the back of the building, from the parking lot.

Accessibility problems – Unfortunately, this location is not wheelchair accessible. It has stairs, and the washroom is up a flight of stairs.

Also, you can still reach the User Group Connect site at the old URL.