Hello! Peter, Bob, thanks for the answers. Here is some my ideas... This message is as long as my first one, sorry. I do my best to explain all things in details :)
Peter, > Are you delivering the output files in the same directories that you use for > versioning the source files? Exactly. > Do you have a reason for keeping the Subversion directory structure in your > links? The main reason is to get more simple documents generation in Apache Cocoon. Due to generation logic based on tokens and wildcards (for details look at sections "Tokenization" and "Wildcard and regular expressions" here: http://cocoon.apache.org/2.0/userdocs/matchers/matchers.html , doc itself is old but described rules haven't changed from that time) it is a convenient way to do it. The main idea is to separate systems and versions to different trees in final URL. For example look here: http://xmlgraphics.apache.org/fop/ (the idea is the same, but it has more flat structure with only one system - FOP): http://xmlgraphics.apache.org/fop/0.95/knownissues_overview.html http://xmlgraphics.apache.org/fop/1.0/knownissues_overview.html Bob, > 1. Generating separate target data files (target.db) in each of your trunk > and branch directories, for each product and guide. This step was already done and exactly as you suggested - each source doc {1}_userguide.xml has its own {1}_userguide.target.db. All targetdb files have already been generated at pre-cocoon level by xsltproc. But following steps are not clear for me... > 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. What do you mean under "identifies which versions of trunk or branches are to be combined based on pathnames to the target data files"? Do you mean make the "local" project/version sitemaps (imagine, target.sitemap.xml) with only "local" target files inside it (i.e. target.sitemap.xml includes only links to trunk mars_userguide.target.db, mars_adminguide.target.db) and then put in each directory (project/system)"? Like this: doc - mars -- trunk (mars_userguide.xml, mars_adminguide.xml, target.sitemap.xml) -- branches --- 1.0 (mars_userguide.xml, mars_adminguide.xml, target.sitemap.xml) --- 2.0 (mars_userguide.xml, mars_adminguide.xml, target.sitemap.xml) - pluto -- trunk (pluto_userguide.xml, pluto_adminguide.xml, target.sitemap.xml) -- branches --- 0.4 (pluto_userguide.xml, pluto_adminguide.xml, target.sitemap.xml) --- 0.8 (pluto_userguide.xml, pluto_adminguide.xml, target.sitemap.xml) > 3. Select the right olink database file at build time using the > target.database.document parameter. Certainly, I can assign target.database.document=/<some_path>/<project_name>/<version_number>/ target.sitemap.xml , give to the stylesheet right <project_name>/<version_number>. Thus (if the previous step #2 realization is what you meant) completely solve the use case 1 (see below my original message). BUT it doesn't solve the case 2 - multiproject(trunk/version). May be I didn't clear define this in my original message, but here the trouble "how the author should define the right document to link to" arise. I.e. in case: pluto/trunk/pluto_adminguide.xml --> mars/branches/2.0/mars_adminguide.xml , the link would be: <para>About installation see <olink targetdoc="mars_usr_adminguide" targetptr="installation"></olink></para>. And it equals any target (the same for doc mars/branches/1.0/mars_adminguide.xml, mars/trunk/mars_adminguide.xml, etc.), because inside any mars_adminguide.xml targetdoc/targetptr don't changed while document branched trunk > 1.0, trunk > 2.0, etc. -- Best regards, Eduard Tibet -----Original Message----- From: Bob Stayton [mailto:b...@sagehill.net] Sent: Wednesday, October 06, 2010 10:28 PM To: Eduard Tibet; docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] Olink logic between different trunk/branches folders of documentation (several projects) Hi, 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 b...@sagehill.net ----- Original Message ----- From: "Eduard Tibet" <eduard.ti...@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) Hello! 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): 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 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 --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org