Publishing documentation on w.g.o

[Curtis Hovey <sinzui cox net>]

I'm upgrading the script we use(d) to publish user, admin, and
accessibility docs to www.gnome.org.  At this moment we do not have any
documentation on w.g.o so I think it time to get this script working.

Documentation is different from most most of our Web content because the
older content is valuable and must be preserved.  I'm considering a new
approach to generating the documentation.

We will publish documentation to a dir structure like this form:

/learn/user-guide/2.0/
/learn/user-guide/2.2/
/learn/user-guide/2.4/
/learn/user-guide/2.6/
/learn/user-guide/head/
/learn/user-guide/latest/

We use a symbolic link to point to the latest stable version of
documentation.  The latest version also has a permanent URL available
for pages must must link to an explicit version.  HEAD will be hidden,
but publicly accessible.  The script will generate user-guide, admin-
guide, and access-guide.

Micro versions (2.6.0, 2.6.0.1, 2.6.1) will all publish to 2.6; we must
be careful to generate the latest revision to a major release.  The cvs
update script will automatically generate head.  A member of Webhackers
may run the script to publish a specific revision.

In the case of the GNOME 2.8 release, the documentation will be
available under head for days or weeks preceding the release.  

1. The GNOME Documentation team will tag the gnome-user-docs with
GNOME_USER_DOCS_2_8_0.  

2. A Webhacker/administrator will run the doc regeneration script and
pass the '-r GNOME_USER_DOCS_2_8_0' argument to make the 2.8 directories

3. A Webhacker/administrator will change the symbolic link from 2.6 to
2.8.

4. A Webhacker will update learn/index.html to add the 2.8 section.

Steps 3 and 4 are awkward in that they must happen at the same time for
a graceful transition, and that someone with administrative powers is
needed.

A different approach to the 'latest' problem is to have a configuration
file that sets the latest version to 2.8, and the content of 2.8 is
copied to latest.  This method could applied to all modules that provide
documentation.  By updating the latest property, all docs from their
respective modules will be published to the Web site.  We still have a
problem of knowing what the latest stable version of documentation is.

My final thought is that we maintain a list of stable versions in a
configuration file.  When we update that file, the documentation is
extracted, generated, and published to the Web site.

Does this seem doable?  Who should have the power to set the latest
version?  Do we need a sanity to ensure all our versions of documents
are published?  Should i just regen the docs by hand, put them back, and
delay a solution until we get library.gnome.org?

-- 
__C U R T I S  C.  H O V E Y____________________
sinzui cox net
Guilty of stealing everything I am.