DENX . DULG . DULGWebLayout
|
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
- The
DULGData.%BOARD%Prefs
topic containg all board specific settings
- 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
Copyright © 2002-2019 by DENX Software Engineering