Maintaining the "w3-recs" Debian package
========================================

The maintenance of w3-recs has been automated as much as possible. The starting
point is a machine-interpretable version of the index of the Technical Reports
(TRs) of the W3C. Such a representation is available as an RDF file on the W3C
web site. From it various kind of information are automatically generated such
as:
- the URLs of all the currently available recommendations to be downloaded
- the doc-base entries
- the HTML version of the recommendation index
- the text version of the recommendation index to be inserted in the
  debian/control long description

Below are reported various debian/rules target and additional utilities which
help in managing the information mentioned above.

Useful debian/rules targets
---------------------------

- get-orig-source

    first download the TR index and then starts mirroring the W3C website using
    the recommendation URLs as starting points. Beware that the mirror takes a
    while (~ 2 hours) and will download about 200 Mb of data

- clean-orig-source

    remove the stuff downloaded by get-orig-source

- build-orig

    build the .orig.tar.gz tarball in ../tarballs/

- maint-build

    create derived stuff that must be included in the source package. This
    includes generating debian/control from debian/control.in including the
    recommendation index in the long description, so you should invoke this
    before creating the source package.  So, *BIG FAT WARNING*, do not change
    debian/control manually since your changes will be overwritten; work on
    debian/control.in and then invoke "fakeroot debian/rules maint-build"

- maint-clean

    remove the stuff generated by maint-build

Useful XSLT stylesheets
-----------------------

- xsl/w3-tr-lib.xsl

    "library" with common functionalities used by the other stylesheets.
    Notably the "find_trs" template selects filter out the Technical Reports
    that will be shipped in this package (ATM it selects recommendations ...
    and yes the TR index contains a lot of stuff other than recommendations).

- xsl/grep-urls.xsl   (e.g. "xsltproc xsl/grep-urls.xsl tr.rdf")

    print out the recommendation URLs (i.e. mirror starting points)

 -- Stefano Zacchiroli <zack@debian.org>  Sun, 16 Sep 2007 12:35:32 +0200

Keeping up to date wrt new Recommendation
-----------------------------------------

If you are interested in maintaining w3-recs, you should now that the routine
required activity is updating shipped recommendations to reflect their new
"releases", as well as including brand new recommendations in the package. The
best way to keep up to date with that business and knowing when new/update
recommendations get released is following the RSS feed of www.w3.org. A direct
link to it is currently http://www.w3.org/2000/08/w3c-synd/home.rss .

 -- Stefano Zacchiroli <zack@debian.org>  Wed, 16 Jul 2008 13:34:01 +0200


Steps to rebuild package from w3 website
----------------------------------------

- clone the git repository of this package.
- start the mirroring of w3.org by invoking first the clean-orig-source target
  to make sure you will download a new index file. Then invoke get-orig-source.
  This takes more or less 2 hours
- invoke the maint-clean and maint-build targets to generate updated docs and
  debian/control files. Check the differences from the previous debian/control
  (by git diff for example) to have the list of the new/updated recommendations.
  If there are differences, change the release number according to the date of
  the mirroring and update the changelog.
- eventually, work on the package (patches...)
- when you want to build a package with the downloaded mirror, build
  the orig.tar.gz with the build-orig target, then move the orig.tar.gz
  from ../tarballs to ../
- build the package as another package (debuild, dpkg-buildpackage...)

 -- Colin Darie <colindarie@gmail.com>  Sat, 18 Dec 2010 04:20:30 +0100


Known issues
------------

The www.w3.org website is not exempt of broken links, resulting in download
errors when wget try to fetch theses resources.
Here is a list of known broken links :
 - http://www.w3.org/1999/07/REC-MathML-19990707/chap6/glyphs/U.gif
 - http://www.w3.org/TR/2003/REC-MathML2-20031021/glyphs/030/U030FF.png
 - http://www.w3.org/TR/2007/REC-sawsdl-20070828/img/todo.png
 - http://www.w3.org/TR/2008/REC-xml-20081126/E01 ... E11
 - http://www.w3.org/TR/2009/REC-PICS-labels-20091124/REC-PICS-services-961031.html
 - http://www.w3.org/TR/2009/REC-PICSRules-20091124/style/default.css
 - http://www.w3.org/TR/2010/REC-xhtml-modularization-20100729/SCHEMA/examples/missing
 - http://www.w3.org/TR/2010/REC-xhtml-modularization-20100729/DTD/examples/missing

Some of them are patched in this package when the real url of the resource has been
found (see debian/patch).

 -- Colin Darie <colindarie@gmail.com>  Sun, 17 Oct 2010 20:27:32 +0200
