DULGWebConcept < DULG

---++ 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, TWiki.TWikiVariables are used in
conjunction with values provided by the TWiki.SessionPlugin plugin.

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

(%H% Because =%<nop>BOARD%= is simply a TWiki variable, you can set it in your
own preference (%WIKIUSERNAME%) 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 =%<nop>BOARD%= variable governs loading of TWiki.TWikiPreferences
from a special topic named =<nop>DULGData.%<nop>BOARD%Prefs=.  This topic specifies
some high-level variables like =%<nop>ARCHITECTURE%= and some low-level
variables like =%<nop>CONSOLE_BAUDRATE%=.  The subordinate webs *DULGData_%<nop>BOARD%* contains
all information specific to =%<nop>BOARD%.
The topic =<nop>DULGData_tqm8xxl.UBootVersion= 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, every board has its own
=<nop>DULGData_%<nop>BOARD%= web.

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

   1 The =<nop>DULGData.%<nop>BOARD%Prefs= topic containg all board specific settings
   1 The topics =<nop>DULGData_%<nop>BOARD%.TopicName= containing usually logs
     or specific information (contained in per-board Webs)

(The topic =<nop>DULGData_%<nop>BOARD%.WebIndex= 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 TWiki.ConditionalPlugin plugin.

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

<verbatim>
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!
</verbatim>

---+++ Linearity

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

<verbatim>
%IF{ "%HAVE_DISK_ON_CHIP%" eq "true" }%
      * [[Disk On Chip]] %ENDIF%
</verbatim>

%X% 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
TWiki.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*.