From: Bob Stayton Date: Mon, 9 Aug 2004 00:22:27 +0000 (+0000) Subject: New parameters to support new olink features. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=fafe241c05b2d8fdf2002fa025059dbf542c2687;p=docbook-dsssl New parameters to support new olink features. --- diff --git a/xsl/params/insert.olink.page.number.xml b/xsl/params/insert.olink.page.number.xml new file mode 100644 index 000000000..13f8b4636 --- /dev/null +++ b/xsl/params/insert.olink.page.number.xml @@ -0,0 +1,75 @@ + + +insert.olink.page.number +string + + +insert.olink.page.number +Turns page numbers in olinks on and off + + + + +no + + + +Description + +The value of this parameter determines if +cross references made between documents with +olink will +include page number citations. +In most cases this is only applicable to references in printed output. + +The parameter has three possible values. + + + +no +No page number references will be generated for olinks. + + + +yes +Page number references will be generated +for all olink references. +The style of page reference may be changed +if an xrefstyle +attribute is used. + + + +maybe +Page number references will not be generated +for an olink element unless +it has an +xrefstyle +attribute whose value specifies a page reference. + + + +Olinks that point to targets within the same document +are treated as xrefs, and controlled by +the insert.xref.page.number parameter. + + +Page number references for olinks to +external documents can only be inserted if the +information exists in the olink database. +This means each olink target element +(div or obj) +must have a page attribute +whose value is its page number in the target document. +The XSL stylesheets are not able to extract that information +during processing because pages have not yet been created in +XSLT transformation. Only the XSL-FO processor knows what +page each element is placed on. +Therefore some postprocessing must take place to populate +page numbers in the olink database. + + + + + + diff --git a/xsl/params/insert.olink.pdf.frag.xml b/xsl/params/insert.olink.pdf.frag.xml new file mode 100644 index 000000000..8939f2798 --- /dev/null +++ b/xsl/params/insert.olink.pdf.frag.xml @@ -0,0 +1,63 @@ + + +insert.olink.pdf.frag +boolean + + +insert.olink.pdf.frag +Add fragment identifiers for links into PDF files + + + + + + + + +Description + +The value of this parameter determines whether +the cross reference URIs to PDF documents made with +olink will +include fragment identifiers. + + +When forming a URI to link to a PDF document, +a fragment identifier (typically a '#' followed by an +id value) appended to the PDF filename can be used by +the PDF viewer to open +the PDF file to a location within the document instead of +the first page. +However, not all PDF files have id +values embedded in them, and not all PDF viewers can +handle fragment identifiers. + + +If insert.olink.pdf.frag is set +to a non-zero value, then any olink targeting a +PDF file will have the fragment identifier appended to the URI. +The URI is formed by concatenating the value of the +olink.base.uri parameter, the +value of the baseuri +attribute from the document +element in the olink database with the matching +targetdoc value, +and the value of the href +attribute for the targeted element in the olink database. +The href attribute +contains the fragment identifier. + + +If insert.olink.pdf.frag is set +to zero (the default value), then +the href attribute +from the olink database +is not appended to PDF olinks, so the fragment identifier is left off. +A PDF olink is any olink for which the +baseuri attribute +from the matching document +element in the olink database ends with '.pdf'. +Any other olinks will still have the fragment identifier added. + + + diff --git a/xsl/params/olink.debug.xml b/xsl/params/olink.debug.xml new file mode 100644 index 000000000..318920a58 --- /dev/null +++ b/xsl/params/olink.debug.xml @@ -0,0 +1,31 @@ + + +olink.debug +boolean + + +olink.debug +Turn on debugging messages for olinks + + + + + + + + +Description + +If non-zero, then each olink will generate several +messages about how it is being resolved during processing. +This is useful when an olink does not resolve properly +and the standard error messages are not sufficient to +find the problem. + + +You may need to read through the olink XSL templates +to understand the context for some of the debug messages. + + + + diff --git a/xsl/params/olink.doctitle.xml b/xsl/params/olink.doctitle.xml index f48f9fa61..9493fb671 100644 --- a/xsl/params/olink.doctitle.xml +++ b/xsl/params/olink.doctitle.xml @@ -1,7 +1,7 @@ olink.doctitle -boolean +string olink.doctitle @@ -9,13 +9,129 @@ - + Description -When olinks between documents are resolved for print output, the generated text may not make it clear that the reference is to another document. It is possible for the stylesheets to append the other document's title to external olinks. For this to happen, two parameters must be set. The olink.doctitle parameter should be set to nonzero to enable this -feature. And you should set the current.docid parameter to the document id for the document currently -being processed for output. If an olink's targetdoc id differs from the current.docid, then the stylesheet can append the target document's +When olinks between documents are resolved, the generated text +may not make it clear that the reference is to another document. +It is possible for the stylesheets to append the other document's +title to external olinks. For this to happen, two parameters must +be set. + + +This olink.doctitle parameter +should be set to either yes or maybe +to enable this feature. + + + +And you should also set the current.docid +parameter to the document id for the document currently +being processed for output. + + + + + +Then if an olink's targetdoc id differs from +the current.docid value, the stylesheet knows +that it is a reference to another document and can +append the target document's title to the generated olink text. + +The text for the target document's title is copied from the +olink database from the ttl element +of the top-level div for that document. +If that ttl element is missing or empty, +no title is output. + + +The supported values for olink.doctitle are: + + + +yes + + +Always insert the title to the target document if it is not +the current document. + + + + +no + + +Never insert the title to the target document, even if requested +in an xrefstyle attribute. + + + + +maybe + + +Only insert the title to the target document, if requested +in an xrefstyle attribute. + + + + +An xrefstyle attribute +may override the global setting for individual olinks. +The following values are supported in an +xrefstyle +attribute using the select: syntax: + + + + +docname + + +Insert the target document name for this olink using the +docname gentext template, but only +if the value of olink.doctitle +is not no. + + + + +docnamelong + + +Insert the target document name for this olink using the +docnamelong gentext template, but only +if the value of olink.doctitle +is not no. + + + + +nodocname + + +Omit the target document name even if +the value of olink.doctitle +is yes. + + + + +Another way of inserting the target document name +for a single olink is to employ an +xrefstyle +attribute using the template: syntax. +The %o placeholder (the letter o, not zero) +in such a template +will be filled in with the target document's title when it is processed. +This will occur regardless of +the value of olink.doctitle. + +Note that prior to version 1.66 of the XSL stylesheets, +the allowed values for this parameter were 0 and 1. Those +values are still supported and mapped to 'no' and 'yes', respectively. + diff --git a/xsl/params/olink.lang.fallback.sequence.xml b/xsl/params/olink.lang.fallback.sequence.xml new file mode 100644 index 000000000..b7aea9eef --- /dev/null +++ b/xsl/params/olink.lang.fallback.sequence.xml @@ -0,0 +1,77 @@ + + +olink.lang.fallback.sequence +string + + +olink.lang.fallback.sequence +look up translated documents if olink not found? + + + + + + +Description + +This parameter defines a list of lang values +to search among to resolve olinks. + + +Normally an olink tries to resolve to a document in the same +language as the olink itself. The language of an olink +is determined by its nearest ancestor element with a +lang attribute, otherwise the +value of the l10n.gentext.default.lang +parameter. + + +An olink database can contain target data for the same +document in multiple languages. Each set of data has the +same value for the targetdoc attribute in +the document element in the database, but with a +different lang attribute value. + + +When an olink is being resolved, the target is first +sought in the document with the same language as the olink. +If no match is found there, then this parameter is consulted +for additional languages to try. + +The olink.lang.fallback.sequence +must be a whitespace separated list of lang values to +try. The first one with a match in the olink database is used. +The default value is empty. + +For example, a document might be written in German +and contain an olink with +targetdoc="adminguide". +When the document is processed, the processor +first looks for a target dataset in the +olink database starting with: + +<document targetdoc="adminguide" lang="de">. + + +If there is no such element, then the +olink.lang.fallback.sequence +parameter is consulted. +If its value is, for example, fr en, then the processor next +looks for targetdoc="adminguide" lang="fr", and +then for targetdoc="adminguide" lang="en". +If there is still no match, it looks for +targetdoc="adminguide" with no +lang attribute. + + +This parameter is useful when a set of documents is only +partially translated, or is in the process of being translated. +If a target of an olink has not yet been translated, then this +parameter permits the processor to look for the document in +other languages. This assumes the reader would rather have +a link to a document in a different language than to have +a broken link. + + + + diff --git a/xsl/params/olink.properties.xml b/xsl/params/olink.properties.xml new file mode 100644 index 000000000..7797bd05d --- /dev/null +++ b/xsl/params/olink.properties.xml @@ -0,0 +1,23 @@ + + +olink.properties +Properties associated with the cross-reference +text of an olink. + + + + + + + + + +Description + +This attribute set is used on cross reference text +from an olink. It is not applied to the +optional page number or +optional title of the external document. + + + diff --git a/xsl/params/prefer.internal.olink.xml b/xsl/params/prefer.internal.olink.xml new file mode 100644 index 000000000..86c2fe3f0 --- /dev/null +++ b/xsl/params/prefer.internal.olink.xml @@ -0,0 +1,73 @@ + + +prefer.internal.olink +boolean + + +prefer.internal.olink +Prefer a local olink reference to an external reference + + + + + + + + +Description + +If you are re-using XML content modules in multiple documents, +you may want to redirect some of your olinks. This parameter +permits you to redirect an olink to the current document. + + +For example: you are writing documentation for a product, +which includes 3 manuals: a little installation +booklet (booklet.xml), a user +guide (user.xml), and a reference manual (reference.xml). +All 3 documents begin with the same introduction section (intro.xml) that +contains a reference to the customization section (custom.xml) which is +included in both user.xml and reference.xml documents. + + +How do you write the link to custom.xml in intro.xml +so that it is interpreted correctly in all 3 documents? + +If you use xref, it will fail in user.xml. + +If you use olink (pointing to reference.xml), +the reference in user.xml +will point to the customization section of the reference manual, while it is +actually available in user.xml. + + + +If you set the prefer.internal.olink +parameter to a non-zero value, then the processor will +first look in the olink database +for the olink's targetptr attribute value +in document matching the current.docid +parameter value. If it isn't found there, then +it tries the document in the database +with the targetdoc +value that matches the olink's targetdoc +attribute. + + +This feature permits an olink reference to resolve to +the current document if there is an element +with an id matching the olink's targetptr +value. The current document's olink data must be +included in the target database for this to work. + + +There is a potential for incorrect links if +the same id attribute value is used for different +content in different documents. +Some of your olinks may be redirected to the current document +when they shouldn't be. It is not possible to control +individual olink instances. + + + +