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 $