|
As discussed in the
FSW Documentation tutorial,
most of FSW's online documents are derived
(i.e., mechanically generated) from other sources of information.
As a result, the pages are far more up to date, information-rich,
cross-linked, and error-free
than manual editing would allow.
This page discusses the constraints and design decisions
that have shaped this software.
Constraints
- Extensibility
Because of evolving project needs and understandings,
it must be convenient to add information sources,
presentation content and formats, etc.
- Portability
The software should run under any Unix-like environment (e.g.,
Cygwin,
Linux, and
Solaris).
The output documents must be accessible
from any modern computer system.
- Sociability
The software must be able to accept data
from pre-existing software systems.
This may arrive in a diverse set of I/O formats,
including text
(e.g., field-delimited records,
XML,
YAML) and
binary (e.g., object code) files,
as well as formal databases
(e.g., MySQL).
The software may be called upon to generate any of these formats,
as well as HTML, PDF, PNG, etc.
Design Decisions
- Infrastructure
The software is written primarily in
Perl.
A few (tiny) Bourne shell scripts are also present,
but they could be recapitulated in Perl, if need be.
The software uses a few common Unix commands,
plus Open Source packages
such as
Doxygen,
Graphviz,
Groff,
and ps2pdf.
It also uses some Perl modules,
including Data::Dumper, XML::Parser,
and YAML.
Note:
Although most of the system runs on a Solaris-based server at SLAC,
the (C language) program that converts image sequences
into QuickTime movies runs (via scp and ssh)
on a desktop Mac OS X machine.
Because the OSX version
of Graphviz does a superior job of rendering,
that part of the production may move over, as well.
- Modularity
The locally-written software consists
of a set of several dozen scripts,
run by a pair of makefiles
(one hand edited, one dynamically generated).
The scripts communicate by means of data files,
in a variety of formats
(e.g., DOT, PostScript, troff/tbl, YAML).
The default file format, however,
is YAML,
a powerful, flexible, text-based, data serialization format.
YAML is used for most inter-script communication
and all hand-edited input (e.g., configuration files).
Because YAML directly supports Perl's lists and hashes,
scripts can load a YAML file
and immediately start using the resulting data structure(s).
These "frozen" data structures are convenient
for both humans and programmers to use,
greatly speeding the development process.
The Documentation Data Flow page
contains specific, detailed information
on the ways in which the scripts and files are used.
|
