OIC SVN Web Manifests - Challenges

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

With regard to providing linkages and navigation among OIC Materials on SVN,
I have been taking advantage of the fact that the OIC SVN server is also a
(special-purpose) web server.  There are some interesting prospects.

 - Dennis

PS: I notice that XHTML content stored in the oic\TestSuite\branches\barth
content does not serve up through the browser interface as web pages.  I
will do some experiments to see if there is an easy way to make that work.

USING OIC SVN TO HOST HYPERTEXT DOCUMENTS

[I suppose it would be useful to express this analysis in just such a
document, perhaps an updating of the one starting at 
<http://tools.oasis-open.org/version-control/svn/oic/SpecAnalysis/constructi
on/construction.htm>
and perhaps extended over other projects on the OIC SVN repository. 

1. WEB ACCESS TO OIC SVN CONTENT.  Web pages, including pages on the OIC
Wiki (another special-purpose web server), can refer to folders and pages in
the OIC SVN Repository via http: URLs.  (The ODF Specification Analysis
pages do that.)

2. WEB ACCESS TO WEB CONTENT IN THE OIC SVN REPOSITORY.  HTML resources in
the SVN repository can be opened as web pages via URLs from other pages and
by opening the HTML resources via web browser access to the OIC SVN Web
interface.  For example, I can open the 001.html file at 
<http://tools.oasis-open.org/version-control/svn/oic/TestSuite/branches/bart
h/odf12/scenarios/part3/3/3/> 
by navigation through the browser.  
   I can also access the file by directly accessing
<http://tools.oasis-open.org/version-control/svn/oic/TestSuite/branches/bart
h/odf12/scenarios/part3/3/3/001.html> 
** PROVIDED THAT THE svn:mime-type IS SET PROPERLY OR THE HTTP content-type
IS SET PROPERLY BY SOME OTHER MEANS **.  (Browser access to the page will
work, but it may be rendered as XML in the browser instead of being rendered
as an XHTML page.  I notice that IE 8 loads the document as an XML document
with color coding, bracket matching, and element indentation, whereas Google
Chrome opens it as a plain text file.  Solutions are needed that work with a
range of common browsers and that gain the cooperation of the OIC SVN
repository web-server functionality as well.)  
   Compare with 
<http://tools.oasis-open.org/version-control/svn/oic/SpecAnalysis/constructi
on/>, 
<http://tools.oasis-open.org/version-control/svn/oic/SpecAnalysis/constructi
on/index.htm>, 
and
<http://tools.oasis-open.org/version-control/svn/oic/SpecAnalysis/constructi
on/construction.htm>
where I have managed to convince the OIC SVN Server to cough up an HTML MIME
type.

3. WEB-NAVIGABLE HYPERTEXTS IN THE OIC SVN REPOSITORY.  Although it is not
possible to over-ride the SVN web interface with index.html or other
intended default pages, it is possible to provide hypertextual connected
material among the HTML/XHTML material in the SVN repository folders by
APPROPRIATE RELATIVE AND ABSOLUTE LINKS to specific pages, not folders, in
the SVN repository.  Whether style sheets and scripts are found properly
will depend on what sort of relative/absolute referencing is accomplished.

4. WEB-NAVIGABLE MIRRORING OF HYPERTEXTS RETRIEVED VIA SVN.  Provided that
relative URLs in such HTML files do not extend in reach beyond the
appropriate, understood minimum working folder containing that material, the
relative URLs will also work properly when viewed in a browser on the
computer where a working-folder hierarchy copy is accessed.  
   For example, on my desktop system, if I double-click on the file-system
directory entry for
"\\whs\Users\orcmid\docs\associazione\standards\OASIS\OIC\oic\SpecAnalysis\c
onstruction\index.htm"
I can navigate around the working-folder copy of 
<http://tools.oasis-open.org/version-control/svn/oic/SpecAnalysis/>
the same as when accessing the material on the SVN server.  (The behavior
differs somewhat when a relative URL names a folder rather than a page, but
it is a comparable behavior.)

5. VERSIONING IMPACTS ON SVN-HOSTED HYPERTEXT MATERIALS.  When a hypertext
is entered at one of its pages on the OIC SVN Server or in a mirrored
working copy, the relative references are going to be resolved up and down
the particular slice of the SVN tree that entry was into.
   Since the same HTML and hyperdocument pages can be found in more than one
place as the result of branching and labeling (and version selection for
viewing) in the SVN repository, it is important to take that into account in
the design of the SVN repository organization with regard to "trunks,"
"branches," and "tags/labeled versions/releases" (whatever the actual
nomenclature happens to be for a project).
   In order to have a reference to a specific version instance, it may be
necessary to use an absolute URL in order to (1) direct out of the working
copy to an SVN-help page that may not be under the same branch or label and
to ensure that a specific target is found, not the latest version on a
trunk-like development location.  This means that working copies may have
HTML pages that necessarily refer to the repository because it is the only
way to have the on-repository and working-copy browser navigation be
consistent.  Still, it is desirable to use relative links as much as
possible.

6. ONE SIZE DOESN'T FIT ALL.  When the OIC SVN Server is not intended to be
the host of the set of hypertext document versions, then other conditions
apply and absolute references into the SVN repository versions of
hyperdocument pages are inappropriate.  But when the OIC SVN Server content
is the authoritative location of the hyperdocument, I think these techniques
are very useful.

 - Dennis