[This note is intented for people with commit access to the uracoli
Web page tree.  If you do not belong to this group of people, you are
not required to understand this. ;-)]

/* $Id: README.htmldocs.txt,v 1.5 2013/02/12 17:13:44 awachtler Exp $ */

In order to make the documentation of the latest stable release
available on the project's web page, it has been decided to cvs import
it into the Web CVS tree.  So it is basically treated for CVS as
`vendor code' which is going to be maintained outside (since it is
produced out of the source code by doxygen).

This touches a few rough edges of CVS.  The following hints are meant
to document the way this import has been arranged, as well as a few
caveats to avoid accidents.

For those who don't read through this document: DON'T EVER RUN `cvs
commit' ON THE HTML DOCS TREE!  (One exception, see below.)

First of all, `cvs import' is one of the less frequently used CVS
subcommands, so many developers aren't really used to its operation.
Thus, it is more likely to make a mistake when using it than say when
performing a `cvs commit'.  Even for seasoned CVS hackers, it is thus
recommended to first try the command using the global -n option (``dry
run''), in order to see what would happen without actually changing
the repository.

The most dangerous part of `cvs import' is that it can create any
arbitrary subtree in the CVS area.  So in the dry run test, watch out
for unexpected `N' flags (meaning that's a new file to be imported).
Since the documentation is generated by doxygen, the set of files
usually remains quite stable, with a few random additions for newly
added chapters.  If all of the files appear to be `N'ew, it is likely
that the repository location is just wrong.

The actual import is handled by unpacking the official HTML
documentation tree that accompanies the respective uracoli release.
Then, cd into the directory generated (where the `index.html' file can
be found), and run the import from there like:

cvs [-z3] [-n] -d $userid@cvs.savannah.nongnu.org:/web/uracoli \
 import uracoli/manual URACOLI $release

The meta variable $userid is (obviously) your User ID on savannah,
while $release is the symbolic release tag.  While this tag is mostly
unimportant, the current convention uses "r_X_Y_Z", with X.Y.Z being
the uracoli version number this documentation set belongs to (e. g.
"r_1_0_2" for the uracoli 1.0.2 docs).

"uracoli/manual" is the import location in the (Web!) CVS
repository, and "URACOLI" is the `vendor-tag' that should always
match the vendor tag used for the initial import (IOW: just keep this
name forever).

After that import, a cvs checkout from the Web CVS repository (in a
different local directory) should yield the updated files.  Note that
`cvs import' will not handle the removal of files, so this needs to be
handled manually in that checked-out tree.  Note that the removal of
files is the only situation where a `cvs commit' is required in this
subtree.

However, if a removed file later on re-appears, it will cause a
conflict on each subsequent import that has to be resolved manually by
copying over the file.  So it's probably better to just leave removed
files stay in the tree, as they are no longer referenced from the HTML
document structure anyway.

In order to prevent CVS from trying to expand any $ ... $ keywords,
all PNG and JPEG files have to be flagged as `binary'.  Unfortunately,
`cvs import' cannot handle this, so it has been done using

cvs admin -kb *.png *.jpg

This should probably be applied again in case new binary file appear
in the tree.  (Still, no `cvs commit' required, `cvs admin' is an
immediate command.)

It's /very/ important that no file in this subtree of the Web page
repository must ever be touched using a normal cvs commit.  Otherwise,
the respective file will leave the vendor branch (i. e. its version
number goes from 1.1.x.y to 1.x), and it needs to be merged manually
after each future import.  All files on the vendor branch will always
become automatically visible after a new vendor-branch import.

Therefore, should any changes be required to these files, they ought
to be made `off-site' (in a separate tree that has /not/ been checked
out of CVS), and then imported again into CVS.  In case changes are
required that are not part of the officially distributed docs tree,
rather invent a new `release' tag (e. g. "r_1_0_2_a") instead of being
tempted to modify a file in the checked-out tree, and cvs commit the
change.

========================================================================

Here are the explicit command lines, I used for 0.0.7

 Get a fresh cvs checkout if needed:
 cvs -d awachtler@cvs.savannah.nongnu.org:/web/uracoli co -d uracoli-web uracoli

 In the uracoli work directory do the following steps:
   cvs tag r_0_0_7
   bash Tools/makerelease.sh 0.0.7
   cd release/uracoli-0.0.7/install/doc/
   cvs -z3 -n -d :ext:awachtler@cvs.savannah.nongnu.org:/web/uracoli import uracoli/manual URACOLI r_0_0_7
   # ... repeat the above command without '-n', if cvs does not complain about conflicts.
   # if all is ok, you'll see the lines:
   #> No conflicts created by this import
   #>
   #> Triggering webpages update...

   cd ..../web-uracoli
   mv manual manual-1
   cvs up -Pd manual
   cvs admin -kb   $(find . -name "*.png" -o -name "*.jpg" -o -name "*.gif")
   .... and now wait until web server is updated ???????

 Update files in download area:
   cd releases
   ls -1 *0.0.8-*gz > putfile
   sed -i 's/^/put /g' putfile
   sftp -b putfile  awachtler@download.savannah.gnu.org://releases/uracoli

 Direct download, bypassing the mirror (only for urgent data exchange needs)
   http://download.savannah.gnu.org/releases-noredirect/uracoli/