An easy way to personalize your content for several target audiences Jirka Kosek

E-mail: jirka@kosek.cz Web: http://www.kosek.cz

2001 Jiří Kosek $Id: profiling.xml,v 1.1 2002/05/15 17:22:26 isberg Exp $

There are many situations when we need to generate several versions of document with slightly different content from the single source. User guide for program with both Windows and Linux port will differ only in several topics related to installation and configuration. It would be futile to create and maintain two different documents in sync. Another real world example – in addition to standard documentation we can have guide enriched with problem solutions from help-desk. It also may be better to store these information in one document in order to make them absolutely synchronized. Several high-end editing tools have built in support for profiling. User can easily add target audiences for any part of document in a simple to use dialog box. User can select desired target audience before printing or generation of other output formats. Software will automatically filter out excess parts of document and pass rest of it to rendering engine. However, if your budget is limited you can not use commercial solutions. In the following text I will show you simple but flexible profiling solution based on freely available technologies.

In the document we mark parts targeted for particular platform or user group. When generating final output version of document we must do profiling i.e. personalization for particular target audience. Only some parts of document are processed. DocBook has built in support for marking document parts – on almost every element you can use attributes os, userlevel and arch. We can store identifier of operating system, user group or hardware architecture here. You can also store profiling information into some general use attribute like role. shows how document with profile information might look. Many existing SGML tools are able to map public identifiers to files on your local file system. Mapping is specified in so called catalog file. List of catalog files to use is stored in environment variable SGML_CATALOG_FILES. On Unix systems you can set this variable by invoking command export SGML_CATALOG_FILES=/usr/lib/catalog on command line. If you want maintain value of the variable between sessions, place this command into startup file, e.g. .profile. In Windows NT/2000 you can set environment variable by issuing command Start Settings Control Pannel System. Then select Advanced card in the dialog box and click on the Environment Variables... button. Using the New button you can add new environment variable into your system. ]]> DocBook documents are often processed by freely available DSSSL and XSL stylesheets. Most DocBook users who want profiling starts with creation of customization layer which filters out some parts of document. This approach has several serious disadvantages. First, you must create profiling customization for all output formats as they are using different stylesheets. This mean that you must maintain same code on several places or do some dirty tricks with importing several stylesheets into one stylesheet. Second drawback is more serious. If you override templates to filter out documents, you can get almost correct output in a single run of stylesheet. If you will closely look on generated output, you will recognize that in the table of contents there are entries for items which should be completely removed by profiling. Similar problems are in several other places – e.g. skipped auto generated numbers for tables, pictures and so on. To correct this one should change all stylesheet code which generates ToC, cross-references and so on to ignore filtered content. This is very complicated task and will disallow you to easily upgrade to new versions of stylesheets. Thus we must use different approach. Profiling should be totally separate step which will filter out some parts of original document and will create new correct DocBook document. When processed with any DocBook tool or stylesheet you will get always correct output from the new standalone document now. Big advantage of this method is compatibility with all DocBook tools. Filtered document is normal DocBook document and it does not require any special processing. Of course, there is also one disadvantage – formating is now two stage process – first you must filter source document and in second step you could apply normal stylesheets on result of filtering. This may be little bit inconvenient for many users, but whole task can be very easily automated by set of shell scripts or batch files or whatever else.

When implementing filter, you can use many different approaches and tools. I decided to use XSLT stylesheet. Writing necessary filter is very easy in XSLT and many users have XSLT processor already installed. Profiling stylesheet is part of standard XSL stylesheets distribution and can be found in file tools/profile.xsl.

If you want to generate Unix specific guide from our sample document () you can do it in the following way. (We assume, that command saxon is able to run XSLT processor on your machine. You can use your preffered XSLT processor instead.) saxon -o unixsample.xml sample.xml profile.xsl "os=unix" We are processing source document sample.xml with profiling stylesheet profile.xsl. Result of transformation is stored in file unixsample.xml. By setting parameter os to value unix, we tell that only general and Unix specific parts of document should be copied to the result document. If you will look at generated result, you will notice that this is correct DocBook document: Many existing SGML tools are able to map public identifiers to files on your local file system. Mapping is specified in so called catalog file. List of catalog files to use is stored in environment variable SGML_CATALOG_FILES. On Unix systems you can set this variable by invoking command export SGML_CATALOG_FILES=/usr/lib/catalog on command line. If you want maintain value of the variable between sessions, place this command into startup file, e.g. .profile. ]]> It is same as the input document, only Windows specific paragraph is missing. Same procedure can be used to get Windows specific version of document. The result generated by profiling stylesheet have correct document type declaration (DOCTYPE). Without it some tools would not be able to process them further. On the result of filtering you can run common tools – for example DSSSL or XSL stylesheets. Stylesheet support several attributes for specifying profiling values. They are summarized in the following list. os This parameter is used for specifying operating system (os attribute) for which you want get profiled version of document. ul This parameter is used for specifying user level (userlevel attribute) for which you want get profiled version of document. arch This parameter is used for specifying hardware architecture (arch attribute) for which you want get profiled version of document. attr Name of attribute on which profiling should be based. It can be used if profiling information is stored in other attributes then os, userlevel and arch. val This parameter is used for specifying value for attribute selected by attr parameter. E.g. setting attr=os and val=unix is same as setting os=unix. sep Separator for multiple target audience identifiers. Default is ;. Current implementation is able to handle multiple profiling targets in one attribute. In that case you must separate identifiers by semicolon: ...]]> It is possible to use different separator than semicolon by setting sep parameter. There cann't be spaces between separator and target names. You can also perform profiling based on several profiling attributes in a single step as stylesheet can handle all parameters simultaneously. For example to get hypothetical guide for Windows beginners, you can run profiling like this: saxon -o xsample.xml sample.xml profile.xsl "os=win" "ul=beginner" As you can see above described profiling process can be used to substitute SGML marked sections mechanism which is missing in XML.

Profiling is necessary in many larger DocBook applications. It can be quite easily implemented by simple XSLT stylesheet which is presented here. This mechanism can also be used to simulate behavior of marked sections known from SGML.