Single Sourcing in Technical Communication

Iris Fibinger
Comet Communication GmbH

80336 Munich
Germany
e-mail: fibinger@comet-comm.de
phonen: ++49-89-5998-9260
fax: ++49-89-5998-9269
webpage: http://www.comet-comm.de/

Keywords: single sourcing, technical communication, technical documentation, technical illustration

Abstract

Technical Communication covers miscellaneous applications:

So far you needed a separate tool for each purpose und had to use several document formats for distribution and archiving. The xml-based format SVG cleans up with this misery, because SVG allows to use one single source for text, illustrations and animations ("Single Sourcing").

Introduction

No term has caused such a sensation in recent years among technical writers and illustrators as "Single Sourcing". The reasons: Enormous amounts of text and image material builds up in documentation and illustration companies. It is not uncommon for individual documents to contain several thousands of pages. If this is translated into several languages, then the administration needs are greater for both texts and graphics (graphics can contain text which must also be translated).

The desire for tool independence is also associated with this. In the meantime there are lots of expensive tools on the market for documentation, graphics, animation and layout. These are often not compatible with one another.

Then there is the fact that documentation and illustrations should often be published in different media. For example with software manuals it is now taken for granted that in addition to the printed documentation there is also online documentation, usually implemented in the software. It is not uncommon that both types of output be maintained independently of one another.

Therefore the tendency to a single source from which everything can be created in one go, is understandable in particular for communication-orientated careers such as technical writers, illustrators, graphic designers and cartographers.

A simple yet very efficient means for single sourcing is the XML approach for two-dimensional Scalable Vector Graphics. This language enables you to convert that for which you would have earlier required several tools and different formats. SVG includes technical options of established standards such as

as well as numerous image formats.

Below is a list of additional advantages:

The two major advantages of SVG in regard to single sourcing are therefore:

The only disadvantage at the moment is the output . SVG 1.0 is not designed as a page description language and therefore does not support page format definitions and page breaks. Therefore it is only suitable for complex documentation in the online area.

Text, Image and Animation from a Single Source

One of the main characteristics of SVG compared with other online standards with the exception of Macromedia Flash is without doubt the fact that you can create texts, graphics and animations. The following example shows a short SVG document that looks like a document generated with Acrobat Destiller (PDF)[1].

Figure 1: Documentation with SVG

With regard to text, you must accept some disadvantages. The biggest problem is that you cannot still achieve a text flow over several lines with SVG 1.0. The individually lines must be tagged separately. There is a similar maintenance problem as with PDFs in Adobe Acrobat with which you can only modify text line by line.

<text x="50" y="50" style="font-family:Verdana; font-size:12;">
<tspan x="50" dy="16">line 1</tspan>
<tspan x="50" dy="16">line 2</tspan>
<tspan x="50" dy="16">etc.</tspan>
</text>

You cannot omit the redundant tag of the attribute x because in SVG characters after the current text position are moved. This means without the attribute x line 2 would follow line 1 in its X position. At least you can minimize the positioning problem for the Y direction: You achieve a relative shifting compared to the previous line using the attribute dy. If you move the outer most <text> element in the Y direction, the other lines are also moved automatically.

Another problem is the block set often used in documentation. This is also not supported by SVG 1.0. Adobe Illustrator solves this problem by tagging each individual text character with <tspan>. This is naturally not optimal.

The SVG tool landscape for documentation has improved (FrameMaker 7.0 and InDesign 2.0 already support the export of SVG). However we can only hope for future SVG versions for open source use. For example, in SVG 1.2 text flow should be possible within one or more rectangles. The Working Draft 1.1 already contained the tags <div>, <p>, <span>, <region> and <br>. They were however removed for the Candidate Recommendation. The support of flush text within any form is planned for Version 2.0.

SVG is initially designed for graphics. That these can be animated provides considerable advantages especially for technical communication. This allows work processes to be reproduced. The following example shows a static graphic: Cogwheels. Click on "run >>", the factors "rotational direction", "speed" and "effect on the other cogwheels" are firstly clarified:

Figure 2: Animation for better understanding

Storage similar to a Database

In particular the fact that SVG is an XML standard is advantageous with respect to data storage. SVG is like a database for graphics. One example are symbol libraries. Constantly recurring symbols are found

The following example shows danger symbols as are often seen in association with chemicals[2]:

Figure 3: Symbols of danger

The symbols were defined within the tag <defs> and can now be called with <use> (e.g. in a template for bottle labels):

<use xlink:href="#SYMBharm" x="50" y="50" />

Figure 4: Bottle lable

For bottle labels with more dangerous chemicals you only need to change the references (IDs) to the symbol and possibly the associated text.

The advantage: The basic layout (pass and cropped marks) is not affected in any way.

Another example in this context is the storage of self-created SVG fonts. Imagine you require special fonts in your company which should be publishable on the Web. In SVG you can create your own fonts and link them to numerous (and international) typographic properties. These fonts are like every other font called with the CSS property font-family:

<text x="100" y="200" style="font-family: 'Comet Sans'">Font</text>

The following example uses this type of font[3]:

Figure 5: SVG font

The disadvantage at the moment is still that with the exception of he standalone browser Batik, no SVG viewer code fragments can be identified and referenced from external documents. To date the graphics to be referenced must still be "stored" in the document itself.

The Right Language at the Right Place

Many companies now provides their websites in different languages. To view the respective languages, you use the corresponding links, often highlights with the respective country's flag. Other websites contain scripts which query the system language of the user's computer. The script detects for example that the user has an English operating system and then automatically loads the English site in the browser window. The common aspect here is that different documents with partially different layout information must be loaded.

Using SVG you already have a considerably more refined solution without the need for scripting. It contains the tag <switch> which works together with the attribute systemLanguage. With systemLanguage you specify the respective system language for one or more child elements of <switch>. The child element whose language specification corresponds to the language of the user's system is rendered. The following is an example[3]:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
<svg width="500" height="100" xmlns="http://www.w3.org/2000/svg">
<title>switch the system language</title>
<switch><!-- *** begin of switch-command *** -->

<!-- ****** The first child-element is a group with english text.
The system language english will be specified with the attribute systemLanguage="en".
If the language of the user system is english, this child-element will be rendered.
In other case, the second or the third child-element (f. e. german) will be shown in
the browser window: ******* -->

<g systemLanguage="en">
<text x="25" y="60" font-size="30">
You have an english System
</text>
</g>

<!-- *** The second child-element will only be shown on
german systems (systemLanguage="de"): *** -->

<g systemLanguage="de">
<text x="25" y="60" font-size="30">
Sie haben ein deutsches System
</text>
</g>

<!-- *** The third child-element contains french text without any requirements.
This text will be shown on all the other systems: *** -->

<g>
<use xlink:href="#IDrect" />
<text x="25" y="60" font-size="30">
C'est le texte alternatif
</text>
</g>
</switch><!-- *** end of switch-command *** -->
</svg>

The result:

Figure 5: Switch the language

Advantages of the <switch> command:

(A general advantage with regard to translations is the fact that SVG is text-based. Particularly compared to graphic programs which always require a lot of computer resources, you work considerably more quickly and more efficiently with the text editor.)

Nonetheless it would of more interesting if the SVG viewer could already identify codes from other documents.

Access to External Namespaces

Namespaces offer in particular two advantages for SVG:

The following example shows an SVG graphic to which the namespace data was added:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
<svg width="800" height="600" xmlns:data="http://www.example.com/statistik/data"
xmlns="http://www.w3.org/2000/svg">
<title>population of Germany</title>
<defs>
<!-- *** The included data-namespace: *** -->
<data:data>
<data:population id="IDpop" country="germany" number="82023000" />
</data:data><!-- *** end of included data-namespace *** -->
</defs>
<!-- *** The radius of following 'circle'-Tag is 0. This should be modified by a script *** -->
<circle id="IDcircle" style="fill:blue;stroke:black;stroke-width:2" r="0" cx="200" cy="250" />
</svg>

The following Java /EcmaScript then reads the value of the attribute number and converts this value with the aid of the surface content formula in the circle radius which is allocated to the circle (IDcircle):

function setRadius(evt)
{
var doc = evt.getTarget().getOwnerDocument();
var PopNum = doc.getElementById('IDpop');
var circle = doc.getElementById ('IDcircle');
circle.getAttribute('r');
var num = PopNum.getAttribute('number');
circle.setAttribute('r', Math.sqrt(num / (2 * Math.PI)) / 50);
}

The result (supplemented with a map of Germany in the background) can be seen below:

Figure 6: Namespaces

If the population of Germany were to double, you would only have to modify the value of the attributes number. The circle radius increases correspondingly.

One Source with DOM Tree Transformation

XML can be transformed with regard to what is advantageous for different publication media. To the question "how" there are several answers. You can use the XML transformation language XSLT. Another simple, and certainly less problematic, option is again to use Java/EcmaScript. Below is our sample documentation. The difference to above is the first two footnotes are displayed like in online help as a popup to the associated text. This way with the enlarged view you do not always have to scroll down to read the text.

Figure 7: Transformation of the DOM

The following lines can be found in the SVG code:

<defs>
<g id="pop_text" pointer-events="none">
<rect x="0" y="0" width="450" height="40" style="fill:rgb(100%,100%,50%); stroke:black;"/>
<text id="popup_text" x="5" y="18" style="stroke:none; font-family:'TimesNewRomanPSMT'; font-size:10;" ></text>
</g>
</defs>

...

<use id="popup" x="0" y="0" xlink:href="#pop_text" style="visibility:hidden;" />

Look first at the <text id="popup_text"> element. It does not contain text. Child elements are later integrated into this element via a script. Additionally using another script the <use> element which references the group pop_text, is made visible:

The function textinto() generates and deletes the new text nodes. The parameter variables target1 and target2 represent two lines of footnote text. If a text only has one line of footnote text, only one parameter is specified when the function is called (of course, for more lines, the script should be optimized).

When the event mouseover begins, the child nodes are formed while they are removed again when the event mouseout begins.

function textinto (evt,target1,target2)
{
   var evtelem = evt.getTarget();
   var doc = evtelem.getOwnerDocument();
   var targ = doc.getElementById ('popup_text');
   var targ1 = doc.getElementById (target1);
   var targ2 = doc.getElementById (target2);
    switch (evt.getType()+'')
      {
// build it
      case 'mouseover':
      if(targ1)
      {
      var buildNode1 = targ1.cloneNode(true);
      buildNode1.removeAttribute('x');
      buildNode1.removeAttribute('y');
      buildNode1 = targ.appendChild(buildNode1);
      }
      if (targ2)
      {
      var buildNode2 = targ2.cloneNode(true);
      buildNode2.setAttribute('x', '5');
      buildNode2.removeAttribute('y');
      buildNode2.setAttribute('dy', '12');  
      buildNode2 = targ.appendChild(buildNode2);
      }    
      break;
// remove it
      case 'mouseout':
      if(targ1)
      {
      var removeNode1 = targ.getFirstChild();
      removeNode1 = targ.removeChild(removeNode1);
      }
      if(targ2)
      {
      var removeNode2 = targ.getLastChild();
      removeNode2 = targ.removeChild(removeNode2);
      }
      break;
      }
}

The function popup(evt) serves to make the element <use> visible or invisible. Also the position if the popup window should depend on the position of the cursor (via the methods getClientX() and getClientY()):

function popup (evt)
{
var evtelem = evt.getTarget();
var doc = evtelem.getOwnerDocument();
var targ = doc.getElementById ('popup');
if(targ)
{
switch (evt.getType()+'')
      {
      case 'mouseover':
      var style = targ.getStyle();
      if (style)
      {
         style.setProperty ('visibility', 'visible');
      }
      break;
      case 'mouseout':
      var style = targ.getStyle();
      if (style)
      {
         style.setProperty ('visibility', 'hidden');
      }
      break;
      }
targ.getAttribute('x');
targ.getAttribute('y');
var X = evt.getClientX()+50;
var Y = evt.getClientY();
targ.setAttribute('x', X);
targ.setAttribute('y', Y);
}
}

The advantage: If the footnote text changes, it changes on both the page and in the popup window.

Short Conclusion

Without a doubt SVG still requires a certain maturity period (just think about the development of HTML). Nonetheless the approaches to an "all-rounder" are definitely there. If the viewers still become smaller and the selection of WYSIWYG software greater, then there is nothing to stop "single sourcing" with SVG.

References

[1] "Engine construction - Cylinder block", W. A. Livesey, 1990. GSCE Motor Vehicle Studies. London: Cassell.

[2] "Sicheres Arbeiten in Chemischen Laboratorien", published by Bundesverband der Unfallversicherungsträger der öffentlichen Hand e. V., April 1996. Germany.

[3] "SVG - Praxiswegweiser und Referenz des neuen Grafikstandards", I. Fibinger, April 2002. Munich: Markt+Technik.


Valid XHTML 1.0!