[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)
Bob,
Because this topic is travelling deeper and deeper and each message contains a lot of information, I want to wonder, if it is in or out of general scope of this mail list due to it very specific theme. If it is out of scope, I can transfer discussion just to your email and add anyone who is interested in this.
I analyzed all previous topics and found out that the main problem is "olink to 'copies'". If we get only one version of many systems we don't get the problem I told about. So the main question that arise is "how to support copies of the documents that could be linked to main tree (trunk)?". But really, not "true" copies - copies from the "targetdoc" point of view, but not copies from the content view (each version doc content differs each from other).
So, while the author make a document he/she, from the one side he is working with the doc copy (old version), but from the other side - with the derivative doc. So even at the step of authoring here is the problem - how to put olink to the _right_ document (because targetdoc's for all versions of target document are the same).
> authoring an olink should require only a targetdoc value and a targetptr value, both of which should be stable names and not require updating in the XML source files as the documents evolve and are translated. 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.
Hm... And what the "version" means in your case - logical unit or physical unit? I suggest, it has some dualism. If someone looks at it straight forward - of course it is a physical link (the part of href attribute value). But... If someone looks by some angle - it is a logical link, because the meaning and logical direction (not presentation!) of the link depends on version it represents even at the time of authoring. Following is some proof of my thoughts...
> At the point of producing a final output product for consumption, someone has to decide which versions are to be linked, because those are the versions to be released.
"someone has to decide which versions are to be linked" - at this point author and only author itself at the time of authoring can say, what version he/she is (have to) linked to. Because no one, except author, knows the subject matter better.
> I'm not expecting you to cover all possible combinations, just the scenarios that you need to produce released output for.
So, perhaps I need to implement some simple mechanism to be filled by the author (see above paragraph) - so to rely on author in that situation. So author decide by itself what exact document version it link to. From my side I need just to collect the data and automatically build sitemaps. The only one problem here if the there are several links to 2 (or more) _different_ versions of the _same_ document. I.e.: "How to setup module A - see details in <pluto_adminguide of version 1.0>" AND in the same document "How to setup module B - see details in <pluto_adminguide of version 2.0>"
> If I'm still not understanding your requirements, perhaps you could describe in more detail how you process and release these documents.
As I see you understand the whole problem. But anyway I can explain you the whole documentation process...
1. Authors create documents. In these documents they have to link to other document/parts very often, because the general software setup (meaning "many parts" - not process) has different projects (modules). Each module released by its own schedule and, in general, can worked alone, but to reach business goals it works with cooperation with each other. That is why the full consistency between modules is a must (not only for software, but also for documentation).
2. After creating documents they are put on subversion for version control (trunk folder). They are stored and edited there while timeline of the current version is going on.
3. At the time of release, trunk version copied into branch by "svn cp URL/trunk/ URL/branches/version_#/" (repository side copying).
4. The presentation for any doc of any branch/trunk is the web site running by Apache Cocoon. It is used for getting sources from local disc (there are some pre-steps that get the sources from svn, verify docs, builds sources with xincludes files inside, builds targetdb files, etc. - these steps are hard to implement in cocoon as servlet), applying xsl transformations (for docs, header, footer, menus, etc) and send the result stream to client browser.
P.S. I have spending about 2 days in searching in google the appropriate solution for the problem before I've posted here my first message with the "Olink logic between different trunk/branches folders of documentation (several projects)". Really, I suggested that the problem has a trivial solutions but just no one before publish it. There are a lot of projects with the same structure as mine (trunk/branches). It was surprised to me, that no one faced this problem before using docbook as authoring tool. So, I suggest, that only means that either docbook is not used in trunk/branch _multiprojects_ systems with rich between-projects links or trunk/branch _multiprojects_ systems haven't automated processing (all such problems solved by hand and human).
--
Best regards,
Eduard Tibet
-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Monday, October 11, 2010 8:57 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 Eduard,
This part I agree with:
> While writing any author can make an olink to other documents. This is the only
> thing I (as a co-author and, additionally, person responsible for out docbook setup)
> can ask him.
As you say, authoring an olink should require only a targetdoc value and a targetptr
value, both of which should be stable names and not require updating in the XML source
files as the documents evolve and are translated. 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.
That pushes the resolution of olinks into physical links onto the processing side, and
that's where I'm getting a little fuzzy on your requirements. As I discovered when I
began implementing olinks, in the end an olink must connect to a rendered document.
By rendered, I mean the XML source must be rendered as HTML, chunked HTML, PDF,
whatever. Only then can you know the output filenames and what the physical link
(href) should be, or even if the target is present (it could be profiled out, for
example). At the point of producing a final output product for consumption, someone
has to decide which versions are to be linked, because those are the versions to be
released. Those are the versions that your final olink database should specify. I'm
not expecting you to cover all possible combinations, just the scenarios that you need
to produce released output for.
I understand the need to automate the process. You could create one or more simple
XML files that contains the specifications for the versions you want to release.
Since the olink database is an XML file, you could generate it on the fly using XSLT
from the specification file.
If I'm still not understanding your requirements, perhaps you could describe in more
detail how you process and release these documents.
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net
----- Original Message -----
From: "Eduard Tibet" <eduard.tibet@i-free.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Monday, October 11, 2010 3:48 AM
Subject: RE: [docbook-apps] Olink logic between different trunk/branches folders of
documentation (several projects)
Bob, thanks for details of your idea!
Unfortunately this is not completely suitable for my needs. The problems arise here:
> olink database file for each _scenario_ that defines a combination of content based
> on versions
As I understand, the sitemaps in your way are based on scenarios. And scenarios are
based on some predefined logic, that logic is defined either by the document author,
or by other person (not a machine!). Unfortunately, I can't predict any scenario that
can happens. We have about 10 authors, each of them has some document to write to.
While writing any author can make an olink to other documents. This is the only thing
I (as a co-author and, additionally, person responsible for out docbook setup) can ask
him. Neither make any other extra documents with files he/she used nor any other
things that is not authoring itself. From the other side I can't manually looked up
for all documents/scenarios that can take place - in that case the whole automation
process take no sense. So your idea is suitable only for situation that allows manual
human hand tuning with just a few documents. My goal is to get fully automatic
processing (no matter how processing passes it will have).
--
Best regards,
Eduard Tibet
-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Friday, October 08, 2010 9:04 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 Eduard,
I meant that you could create an olink database file for each scenario that defines a
combination of content based on versions. If you place these above the source
directories, the paths in each file would indicate which version of each book is used
in each such combination.
For example, in a scenario that uses only trunk versions, create this database file:
doc/olink-trunk.xml:
<!DOCTYPE targetset [
<!ENTITY pluto_adminguide SYSTEM "pluto/trunk/pluto_adminguide.target.db">
<!ENTITY pluto_userguide SYSTEM "pluto/trunk/pluto_userguide.target.db">
<!ENTITY mars_adminguide SYSTEM "mars/trunk/mars_adminguide.target.db">
<!ENTITY mars_userguide SYSTEM "mars/trunk/mars_userguide.target.db">
]>
<targetset>
<sitemap>
<dir name="doc">
<dir name="pluto">
<dir name="trunk">
<document baseuri="pluto_adminguide.html" targetdoc="pluto_adminguide">
&pluto_adminguide;
</document>
<document baseuri="pluto_userguide.html" targetdoc="pluto_userguide">
&pluto_userguide;
</document>
</dir>
</dir>
<dir name="mars">
<dir name="trunk">
<document baseuri="mars_adminguide.html" targetdoc="mars_adminguide">
&mars_adminguide;
</document>
<document baseuri="mars_userguide.html" targetdoc="mars_userguide">
&mars_userguide;
</document>
</dir>
</dir>
</dir>
</sitemap>
</targetset>
The entities define which target.db files to use, and the sitemap specifies the output
locations. Now when you process any of the documents in trunk, specify
target.database.document="doc/olink-trunk.xml" (with suitable adjustments for path
relative to the processing directory).
And when you roll pluto to 0.95 and mars to 2.0, create olink-pluto95-mars2.xml for
that combination, changing the entity declarations to load new data files, and
changing the sitemap to match your output structure:
<!DOCTYPE targetset [
<!ENTITY pluto_adminguide SYSTEM "pluto/branches/0.95/pluto_adminguide.target.db">
<!ENTITY pluto_userguide SYSTEM "pluto/branches/0.95/pluto_userguide.target.db">
<!ENTITY mars_adminguide SYSTEM "mars/branches/2.0/mars_adminguide.target.db">
<!ENTITY mars_userguide SYSTEM "mars/branches/2.0/mars_userguide.target.db">
]>
<targetset>
<sitemap>
<dir name="doc">
<dir name="pluto">
<dir name="branches">
<dir name="0.95">
<document baseuri="pluto_adminguide.html" targetdoc="pluto_adminguide">
&pluto_adminguide;
</document>
<document baseuri="pluto_userguide.html" targetdoc="pluto_userguide">
&pluto_userguide;
</document>
</dir>
</dir>
</dir>
<dir name="mars">
<dir name="branches">
<dir name="2.0">
<document baseuri="mars_adminguide.html" targetdoc="mars_adminguide">
&mars_adminguide;
</document>
<document baseuri="mars_userguide.html" targetdoc="mars_userguide">
&mars_userguide;
</document>
</dir>
</dir>
</dir>
</dir>
</sitemap>
</targetset>
Then set target.database.document="doc/olink-pluto95-mars2.xml" when process those
versions.
Would this setup satisfy your requirements?
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net
----- Original Message -----
From: "Eduard Tibet" <eduard.tibet@i-free.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Friday, October 08, 2010 5:55 AM
Subject: RE: [docbook-apps] Olink logic between different trunk/branches folders of
documentation (several projects)
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:bobs@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
bobs@sagehill.net
----- 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)
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-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
---------------------------------------------------------------------
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]