(Posted: 6 Dec 2007)


doc-multiSet/
    The directory doc-multiSet/ will not appear in the final version;
    the final structure will be one of the following.  

            HDF5/
               doc  ->  doc1.8 (soft link or duplicate) (doc-softlink)
               doc1.6/
               doc1.8/

            HDF5/
               doc/index.html (with links)              (doc-pointers)
               doc1.6/
               doc1.8/

    As illustrated above, the names 'doc-softlink' and 'doc-pointers' 
    in this setup will be replaced by the name 'doc'.

RFC
    All of the proposed approaches create an issue for the already-
        released and distributed 1.6.6 doc set; that set points to 
        a UG at hdfgroup.org/HDF5/doc/UG.
        None of the proposals allow for this, but a directory can
        be added as a patch.



                     HDF5/
                   /  |  \  \
                  /   |   \   \
                 /    |    \    \
                /     |     \     \  
               /      |      \      \
             doc   doc1.8/   UG/   doc1.6/
              ^
              ^
               \<------------ If this is a soft link to
              ^               the current "dominant" release (RFC
              ^               Option 3), it will already contain 
              ^               a UG/ (but 1.8, not the 1.6.6 UG).
              ^
               \<------------ If this is a page with pointers
                              to specific releases (RFC Option 2), 
                              a UG/ subdir will be added (with the 
                              1.6.6 UG).

        In the first case, the UG will not be the 1.6.6 UG, but
        most (and maybe all) of the links into it should work.
        Links back to other docs from the UG will take the user
        into the 1.8 doc set, which will undoubtedly be unexpected
        if the user got the user's local copy of the 1.6 docs.
        (1.6 docs on our site will be adjusted to work properly.)

        In the second case, it's a little out of place, but not 
        particularly ugly (from a distance), and it should prevent 
        (or at least minimize) link failures with a few link 
        adjustments.


1.6 branch
    Checked out on "1.6 branch" rather than on "1.6.6 tag."
        Reason: At this point, updates are likely to be corrections
            rather than new functionality.
        Potential flaws: 
            Posted docs may not exactly match released tarball; 
                posting may be more current.  Differences, however,  
                are likely to be small and "more correct."
            Will be necessary to exercise caution in SVN updates
                as 1.6.7 approaches and footers and release tags
                change.

1.8 branch
    Checked out from hdf5doc trunk.
        1.8 has not yet been branched, let alone 1.8.0 tagged!
        Checkout will have to be changed (to branch or tag?)
            at time of release.