[This note is intented for people with commit access to the avr-libc
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.6 2007/05/15 05:22:23 joerg_wunsch 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 avr-libc 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 address@hidden:/web/avr-libc \
 import avr-libc/user-manual AVR-LIBC $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 avr-libc version number this documentation set belongs to (e. g.
"r_1_0_2" for the avr-libc 1.0.2 docs).

"avr-libc/user-manual" is the import location in the (Web!) CVS
repository, and "AVR-LIBC" 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.  So far, it is envisioned
that the files `tree.js' and `treeview.js' will eventually disappear
when switching the doxygen version from 1.2.x to 1.3.x, while all
other files will probably remain unless the doxygen structure of
avr-libc will be changed.  Note that the removal of files is the only
situation where a `cvs commit' is required in this subtree.

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

cvs admin -kb *.png

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.

Alas, all files that have "reappeared" (were deleted in the past, but
are now part of the documentation again) will cause an import conflict,
and have to be manually dragged over, and "cvs commit"ted.

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.

Similarly, the installed examples need to be imported into

cvs [-z3] [-n] -d address@hidden:/web/avr-libc \
 import avr-libc/examples AVR-LIBC $release

Remove all *.dox *.fig *.jpg files before importing the examples.

Finally, please make sure to also update the NEWS.txt file in the web
base directory.  (No CVS import needed, just copied over from the
source tree to here.  Suffix .txt added to aid in suffix-based
content-type decisions.)