Guide to SWAD-Europe online documentation
-
version:
-
$Id: projdocs_guide.html,v 1.1 2002/02/07 17:58:53 danbri
Exp $
Overview: what is this?
The project documentation for SWAD-Europe is complex.
This document provides an overview of the various
documents (both static and evolving) that describe the
project. These include the core 'description of work' files,
and a number of documents and summaries derrived from these
files. We are attempting to keep our primary materials in
textual form (mainly HTML) and generate other formats as and
when needed, for example for various submission to the
European Commission. We also have to deal with a certain
amount of redundancy and duplication; eg. tables of contents,
summaries etc in various formats (spreadsheets, MS Word .doc
files, Gantt charts etc). Although the basic shape of the
project should be stable once the Description of Work is
finalised, the project documentation will need to continue
evolving, while staying consistent with our formal
commitments to the EU. This document attempts to keep track
of everything we need to achieve this.
Project Documentation
The original bid was drafted as HTML, converted to MS Word,
and managed using Word and Excel. We have now converted the
main text back to XHTML, alongside extracts from the
spreadsheets and CFP forms.
Primary Sources
-
notes/concat.txt, config
file specifying source documents that are included in
Description of Work ('DoW'). Note: some source files are
generated.
-
XHTML workpackage descriptions: esw-wp-1.html.. esw-wp-15.html (see wps/ file listing). One WP per XHTML
file.
-
Non-Workpackage documents for DoW
(some prose, some tables)
-
figures from CPF and
spreadsheet, as XHTML table (will use for consistency
checking). (@@todo: libby, will this be updated again?)
-
partners.rdf, a basic RDF
description of partners, not currently used
-
old-new.txt, documents the
workpackage renaming, Feb 2002. Shouldn't be needed much
now, except for reference when dealing with old material or
accidental references to old number scheme. New numbers are
single digit.
-
deliverables list (extracted from
original bid? not actively maintained, since we can
generate this from metadata)
-
style/, CSS style sheet used to
annotate HTML for presentation and/or extraction.
-
Most of the files in dow/ are for
inclusion in the DoW; other useful notes (for local use)
can be found in notes/ directory. The
notes/concat.txt file should
be authoritative w.r.t. which docs are included in the
overall DoW. (the concat.txt document and this current
guide do the same job...?)
Generated Documents
Several important documents are generated from other source
files, and should not themselves be edited. These generally
have filenames beginning with '_', and are (despite being
derrived content) often checked into the w3.org versioning
system. Note that doing a 'make clean
' in this
dow/wps/ directory will zap the more transient of these
files, and that some versions of these might be checked into
CVS for online accessibility.
-
Complete XHTML DoW document: _concat.html. This is generated
from the list of documents in notes_concat.txt, with some
additions and edits (eg. image/chart inclusion) controlled
by the concat.pl perl script. This
document will also be converted into MS Word.
-
Effort split charts: fig/_chartindex.html, a
generated index page for charts (built by
extract_projdata.pl) that show the per-WP split of effort
between partners. The individual images (SVG, PNG) are
added to _concat.html by concat.pl. See figs/ directory for generate files
(including _*.dat data files used by charting tool).
-
Dependency charts: we build SVG and PNG diagrams showing inter-WP
dependencies. There (by design) aren't many hard
dependencies, however we will eventually want to map softer
relationships within the project, within W3C and within the
wider community. The diagrams are built from wp-deps.dot, a hardcoded config
graphviz file. @@todo: This should be generated from other
sources, as graphviz's .dot syntax is the wrong format to
store this data, since it should be consumed by other
summarisation tools too. @@todo: categorise dependency
types ('closely-linked', 'uses', etc. also chrono stuff for
gantt chart? precedes etc?).
-
_auto.html, old debug document,
generated table-of-contents overview doc (built by
extract_projdata.pl via _bydate.txt and _tmp_summary.txt)
technical doc management tools
A few text-based scripts are used to manage these documents.
These are not currently documented for a general audience.
They are used in conjunction with CVS versioning and the
w3.org W3C web server.
All HTML documents are managed as XHTML, and kept tidy/valid
using the HTML Tidy commandline tool, tidy -m -asxml
-indent filename.html
.
Note that doing a 'make clean
' in the dow/wps/
directory will delete various transient files, and that some
versions of these might be checked into CVS for online
accessibility. This may cause confusion, but is needed
because the derrived content has to be accessible via the WWW
at w3.org.
-
extract_projdata.pl, main
perl script for extracting, checking, summarising and
reporting (in HTML and PNG/SVG images) on the work. In the
future one might use XSLT/SVG/MathML/etc to do this. Right
now, a Perl script is fine.
-
Makefile, basic operations on the
document-set
-
mktoc.pl, quick script, soon
obsolete?
-
Graphing software:
plotutils-2.1.4 RPM (or debian: apt-get install
plotutils; apt-get install libplot-dev. See biggles
library for more download links. Fiddly.
NOTE: the work packages were renumbered in
Feb 2002. The new documents are named
esw-wp-n.html
and map to the original
workpackage structures as follows.
list of deliverables
Libby's notes from
negotiations
Software Dependencies
The chart/diagram tools introduce dependencies. This is a
placeholder for better documentation on these tools.
error: failed dependencies: libplot is needed by
plotutils-2.4.1-4 libplot.so.2 is needed by plotutils-2.4.1-4
libstdc++.so.2.10 is needed by plotutils-2.4.1-4 libplot is
needed by plotutils-2.4.1-4 libstdc++ is needed by
plotutils-2.4.1-4
$Id: projdocs_guide.html,v 1.1 2002/02/07 17:58:53 danbri Exp
$
Dan Brickley