OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Olink logic between different trunk/branches folders ofdocumentation (several projects)


I have a general question regarding olinks logic in (and between) multiple projects with trunk/branches folders. In "DocBook XSL: The Complete Guide" samples (http://www.sagehill.net/docbookxsl/Olinking.html#LinkBetweenDocs) are very useful for understanding the principles, but they concern only limited numbers of simple situations (1 project, no branch/trunk). I have more complex task with several projects, trunk, branches, etc. I'll explain the current situation in details...

Imagine, we have 2 projects (systems) - mars and pluto (i've simplified the sample a little bit for better understanding, but the general idea is kept untouched). All documentation (xml source) for these projects stores in (number of "-" equals to folder depth):

 - mars
  -- trunk (mars_userguide.xml, mars_adminguide.xml)
  -- branches
  --- 1.0 (mars_userguide.xml, mars_adminguide.xml)
  --- 2.0 (mars_userguide.xml, mars_adminguide.xml)

 - pluto
  -- trunk (pluto_userguide.xml, pluto_adminguide.xml)
  -- branches
  --- 0.4 (pluto_userguide.xml, pluto_adminguide.xml)
  --- 0.8 (pluto_userguide.xml, pluto_adminguide.xml)

The output structure (html files) is the same (with one page html files - non chunked). All sources are stored in Subversion (http://subversion.apache.org/), all final documentation are generated from sources by Apache Cocoon (http://cocoon.apache.org/), so any actions (fixes) that generally can be done by hand are not possible. Only one of the projects can be branched at the some specific time (I mean there is impossible, that both projects branched from the trunk simultaneously). 

There are 2 typical use cases (olinks shown as -->):

1. {1}.xml  --> {2}.xml (both files within trunk, or within branch/version after branching). For example, pluto/trunk/pluto_userguide.xml --> pluto/trunk/pluto_adminguide.xml; after branching pluto/branches/0.95/pluto_userguide.xml --> pluto/branches/0.95/pluto_adminguide.xml.

2. {1}.xml (from any trunk folder) --> {2}.xml (within exact branch of exact project). For example pluto/trunk/pluto_adminguide.xml --> mars/branches/2.0/mars_adminguide.xml). After branching {1}.xml have to --> the same branch folder (i.e., after branching pluto/trunk/pluto_adminguide.xml into pluto/branches/0.95/pluto_adminguide.xml it still have to --> mars/branches/2.0/mars_adminguide.xml).

I've found some problems, while planning customization layer for these use cases.

Olink sitemap should have unique document targetdoc. For simple documents I usually use current.docid=/*/@id, and document_root_id (/*/@id)= document_filename for simplification. But in this situation it doesn't work:

In case #1 after branching pluto/branches/0.95/pluto_userguide.xml should link to branched pluto/branches/0.95/pluto_adminguide.xml - not to pluto/trunk/pluto_userguide.xml that becomes new version for developers.

In case #2 targetdoc of mars_adminguide.xml should be distinguished from others mars_adminguide.xml (in trunk/other branches) at the time of creating olink (i.e. targetdoc should contains the version number (trunk/<number>)). But, at the time of initial creation mars_adminguide.xml it was trunk - all documents are trunk and there is no possible to predict in what exact version number it will be branched next time. Moreover files (and filenames) itself are not changed after making branches.

How to distinguish different versions of document in this situation? If you know or hear about best practices in that specific field, please, let me know or post the links where I can read more detailed information about it (unfortunately searching for it in Google gave no enough information).

Best regards,
 Eduard Tibet

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]