The concept behind the DULG Wiki

Using a Wiki collaboration platform to maintain documentation for several target platforms with lots of output examples captured from running systems poses two general problems:

Adaptivity

How to generate multiple versions of the same web for different views

Linearity

How to map a mind-map like a Wiki onto a linear page order suitable for printed documentation

Maintainability

How to maintain the large number of log files needed for displaying board specific output

The next sections try to explain how these problems are solved in the DULG web.

Adaptivity

Throughout all of the documentation, TWikiVariables are used in conjunction with values provided by the SessionPlugin plugin.

The main variable concerning the rendering process is the %BOARD% variable. It is either set from the SessionPlugin to the currently selected value or read as a TWikiPreferences value if session support does not work (e.g. client does not accept cookies).

( Because %BOARD% is simply a TWiki variable, you can set it in your own preference (Main.guest) page if you cannot accept cookies for any reason. This way of switching views is cumbersome but at least it works without any session support)

The value of the %BOARD% variable governs loading of TWikiPreferences from a special topic named DULGData.%BOARD%Prefs. This topic specifies some high-level variables like %ARCHITECTURE% and some low-level variables like %CONSOLE_BAUDRATE%. The subordinate web DULGData contains all "board specific" information in topics named according to the schema %BOARD%TopicName where TopicName identifies the output contained in it. The topic DULGData.tqm8xxlUBootVersion for example contains the output of the version command of U-Boot on a TQM8xxL board. To ease maintenance of all the data files for a specific board, there is a DULGData.%BOARD% topic which indexes the files on the fly.

To summarize, a board (and therefore a view of the DULG web) is described by

1. The DULGData.%BOARD%Prefs topic containg all board specific settings
2. The topics DULGData.%BOARD%TopicName containing usually logs or specific information

(The topic DULGData.%BOARD% is a good entry point to browse through all specific files)

The variables defined like this are used throughout the documentation in two ways, i.e.

• as text substitution variables
• as "conditional variables" together with the ConditionalPlugin plugin.

The latter usage allows to incorporate architecture specific informations with constructs like

Boards based on the 
%IF{ %ARCHITECTURE% eq powerpc }% PowerPC %ENDIF%
%IF{ %ARCHITECTURE% eq arm }% ARM %ENDIF%
%IF{ %ARCHITECTURE% eq mips }% MIPS %ENDIF%
platform are most fun to work with!

Linearity

To map the DULG web to the linear form of printed documentation, the TocPlugin plugin is used heavily in the DULG web together with the ConditionalPlugin by conditionalizing the WebOrder topic itself. Whole sections can be bound to a condition with constructs like

%IF{ %HAVE_DISK_ON_CHIP% eq true }%
      * [[Disk On Chip]] %ENDIF%

Note that changes in the WebOrder topic can easily change the structure of the whole documentation, so think twice before going ahead.

To ease the linear viewing of the Manual a toc footer was implemented providing every topic referenced in WebOrder with dynamically generated next/prev/home navigational aids.

There is also a somewhat experimental way to assemble all topics relevant for a specified view into one large HTML file for printing the documenation and the PublishAddOn plugin can be used to generate pre-rendered documentation where each topic generates one HTML file keeping the link structure itself intact.

Maintainability of automatically generated data files

In order to be able to maintain the large number of board specific data files in the DULGData web, an Expect based framework is being worked on that can be used to automatically generate the needed files for a specific board. Actually this should only be a side product from running regression tests verifying the expected operation of certain test cases.

Right now this framework is not "clean enough" to be released into the free, but as soon as we consider it stable, it will be released on this web enabling all users to provide data specific to their board and incorporate it into the documentatoin without intervention from anyone.

-- DetlevZundel - 06 Aug 2003