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: Re: [docbook-apps] Olink logic between different trunk/branches folders of documentation (several projects)

If I understand correctly, I think you can handle this situation by:

1.  Generating separate target data files (target.db) in each of your trunk and branch 
directories, for each product and guide.

2.  Creating multiple olink database files, each of which identifies which versions of 
trunk or branches are to be combined based on pathnames to the target data files.

3.  Select the right olink database file at build time using the 
target.database.document parameter.

The targetdoc and targetid values and olink references remain stable and don't require 
changing.  The only thing that changes is which data sets they are resolving to.  The 
branch number would appear only in the olink database file as part of the pathname to 
a target.db file.

Would that work for you?

Bob Stayton
Sagehill Enterprises

----- Original Message ----- 
From: "Eduard Tibet" <eduard.tibet@i-free.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Wednesday, October 06, 2010 4:34 AM
Subject: [docbook-apps] Olink logic between different trunk/branches folders of 
documentation (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 

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 --> 

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

To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

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