RE: [docbook-apps] Olink logic between different trunk/branchesfolders of documentation (several projects)

[Eduard Tibet <eduard.tibet@i-free.com>]

Bob, Sam, thanks for the ideas, you have brought about 1 month ago!

I've finally created the complete solution for using the olinks in my usecase. If anyone interested in it, I include the concept of it (look at the following text).

So, the initial structure was:
/doc
 - 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 same structure (except of extensions changed from .xml to .html) is for output.

I use current.docid = /*/@id = doc filename

The following ways of olinking are possible/prohibited:

Possible:
1. trunk -> trunk (within one project, the arrow shows the olink direction)
2. trunk -> branch (within two different projects).

Prohibited:
3. branch -> trunk (within any project, within two different projects). Within one project - it has no sense; Within any 2 projects - it prohibited, because to the date of releasing trunk doc can lost the topic it has (or text can lost the initial meaning we mentioned at the time of creating olink). 
4. trunk -> trunk (within two different projects). Reasons - the same (see previous list item).

When an author creates the olink he/she makes a "combined" targetdoc: <docid>-<version_nr> (targetptr used as is). If author links to trunk (same project) it uses no '-<version_nr>'

Let's imagine we link from mars project (mars_userguide document).

i.e. for trunk -> trunk (1): <olink targetdoc="mars_adminguide" targetptr="mars_adminguide_intro">
i.e. for trunk -> branch (2): <olink targetdoc="pluto_userguide-0.4" targetptr="pluto_userguide_intro">

The master target database is generated automatically using dir structure and uses corresponding versions numbers.

i.e.
<!ENTITY mars_adminguide-1.0  SYSTEM "path/mars/branches/1.0/mars_adminguide.target.db">
<!ENTITY mars_adminguide SYSTEM "path/mars/trunk/mars_adminguide.target.db">

The current version # is supplied by cocoon tokens, so the current document always "knows" what version it belongs to (despite the fact it has the same root id, filename, etc as others "mars_userguide" docs). So olinks are always correctly resolved.

The only problem I faced was with case (1) after branching. So, from the one hand documents still have the same links, but from the other, relative position of the documents are changed after branching (they belongs to branched "numbered" path) so it has to link to branched version (not trunk one), so it need to be updated. This issue was resolved using converting of all such links (using current branch #) at preprocess stage just before cocoon processing.

--
Best regards,
 Eduard Tibet

-----Original Message-----
From: Sam Fischmann [mailto:sam.fischmann@gmail.com] 
Sent: Tuesday, October 12, 2010 10:54 PM
To: Eduard Tibet
Cc: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Olink logic between different trunk/branches folders of documentation (several projects)

It seems that you want to link arbitrarily from any version of any
document into any version of any other document.  Generally, I don't
think this is a good idea, because it's rather confusing to link to
two different versions of one book from one version of another. I
would think the customer only wants to have one version of each
product installed. The "blessed combination" approach mentioned by Bob
above seems like it would yield better results. That being said, if
it's truly a requirement and that is the way your products are
designed, then you have to do something about it... so provided that
is the case:

Unless filenames, section titles, element ids, and organization do not
change whatsoever among any versions of any product, you really have
to consider each version of each document as a unique item. Consider
what Bob stated above:

"There should be no version information in those attribute values.
This makes an olink a logical link between documents, not a physical
link like an href."

I still think the second part is correct, but in your case, the
version information you need to add is really information that
distinguishes between two different documents with potential
differences in organization, titles, and ids. If this were my
requirement, I would:

1) Maintain a branch file that keeps track of each project and each
branch within each project. Each branch gets a unique prefix of some
sort. This would be the only file you'd have to maintain by hand.

2) Write some script or transform to read the branch file and iterate
over each branch for each project to build links and/or assemble the
portion of the target database file for that branch, and store the
final target database in trunk or some other external location. The
targetdoc attributes get the prefixes mentioned above.

3) In your build process, invoke this script before building the
documentation set. For the current doc id have your build script look
up the prefix and prepend it to the current id (better than doing this
manually so you don't have to update ids every time you branch).

4) Tell authors about the prefixes, and instead of getting them to
keep track of some weird algorithm, tell them they can see all the
prefixes for their olinks in the branch file from step 1.

5) If you link from a branch's documents to the trunk version of
product X, you'll have to update the prefixes for some of those links
when you branch product X. Because this is going to be a contextual
decision, it cannot be automated unless you come up with yet another
unique prefix to distinguish between consistent trunk links and trunk
links that are really placeholders for the next release of the target
document.

For what it's worth, that database is going to get humongous; every
time you process anything with olinks, the stylesheets are going to
load up the link database for every document you've ever created. I
don't think that these link databases are loaded on-demand, so your
memory needs will grow a lot over time, especially if you release
often. It might be a big enough problem to make this untenable as a
long-term solution.

Hope that helps in some way,

-Sam