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

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,


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