From b9fdd054982f0e304f0521ac237041c7595e4f65 Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Tue, 5 Jul 2005 09:19:17 +0000 Subject: [PATCH] Implemented capability for users to customize "refentry metadata gathering" by specifying XPath expressions to use as "info profiles" for gathering the data, and, in some cases, to suppress parts of the data collected. --- xsl/manpages/param.ent | 6 ++ xsl/manpages/param.xweb | 16 +++- xsl/params/refentry.date.profile.xml | 35 +++++++ .../refentry.manual.fallback.profile.xml | 43 +++++++++ xsl/params/refentry.manual.profile.xml | 67 ++++++++++++++ .../refentry.source.fallback.profile.xml | 44 +++++++++ xsl/params/refentry.source.name.profile.xml | 91 +++++++++++++++++++ xsl/params/refentry.source.name.suppress.xml | 2 +- xsl/params/refentry.version.profile.xml | 39 ++++++++ xsl/params/refentry.version.suppress.xml | 2 +- 10 files changed, 341 insertions(+), 4 deletions(-) create mode 100644 xsl/params/refentry.date.profile.xml create mode 100644 xsl/params/refentry.manual.fallback.profile.xml create mode 100644 xsl/params/refentry.manual.profile.xml create mode 100644 xsl/params/refentry.source.fallback.profile.xml create mode 100644 xsl/params/refentry.source.name.profile.xml create mode 100644 xsl/params/refentry.version.profile.xml diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent index def66b94c..577ec4458 100644 --- a/xsl/manpages/param.ent +++ b/xsl/manpages/param.ent @@ -17,3 +17,9 @@ + + + + + + diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb index 55779ab0a..c90e75043 100644 --- a/xsl/manpages/param.xweb +++ b/xsl/manpages/param.xweb @@ -49,12 +49,18 @@ Refentry metadata gathering +&refentry.date.profile; &refentry.date.profile.enabled; +&refentry.manual.profile; &refentry.manual.profile.enabled; -&refentry.source.name.profile.enabled; -&refentry.version.profile.enabled; &refentry.source.name.suppress; +&refentry.source.name.profile; +&refentry.source.name.profile.enabled; &refentry.version.suppress; +&refentry.version.profile; +&refentry.version.profile.enabled; +&refentry.manual.fallback.profile; +&refentry.source.fallback.profile; The Stylesheet @@ -98,6 +104,12 @@ + + + + + + diff --git a/xsl/params/refentry.date.profile.xml b/xsl/params/refentry.date.profile.xml new file mode 100644 index 000000000..96acfcca0 --- /dev/null +++ b/xsl/params/refentry.date.profile.xml @@ -0,0 +1,35 @@ + + +refentry.date.profile +string + + +refentry.date.profile +Specifies profile for refentry "date" data + + + + + + ($info/date + |$info/pubdate + |$parentinfo/date + |$parentinfo/pubdate)[1]/node() + + + + +Description + +The value of refentry.date.profile is a +string representing an XPath expression. It is evaluated at run-time +and used only if refentry.date.profile.enabled +is non-zero. Otherwise, the refentry metadata-gathering +logic "hard coded" into the stylesheets is used. + + The man(7) man page describes this content +as "the date of the last revision". In man pages, it is the content +that is usually displayed in the center footer. + + + diff --git a/xsl/params/refentry.manual.fallback.profile.xml b/xsl/params/refentry.manual.fallback.profile.xml new file mode 100644 index 000000000..ce137428b --- /dev/null +++ b/xsl/params/refentry.manual.fallback.profile.xml @@ -0,0 +1,43 @@ + + +refentry.manual.fallback.profile +string + + +refentry.manual.fallback.profile +Specifies profile of "fallback" for refentry "manual" data + + + + + +refmeta/refmiscinfo[1]/node() + + + +Description + +The value of +refentry.manual.fallback.profile is a string +representing an XPath expression. It is evaluated at run-time and +used only if no "manual" data can be found by other means (that is, +either using the refentry metadata-gathering logic "hard +coded" in the stylesheets, or the value of +refentry.manual.profile, if it is +enabled). + + +Depending on which XSLT engine you run, either the EXSLT +dyn:evaluate extension function (for xsltproc or +Xalan) or saxon:evaluate extension function (for +Saxon) are used to dynamically evaluate the value of +refentry.manual.fallback.profile at +run-time. If you don't use xsltproc, Saxon, Xalan -- or some other +XSLT engine that supports dyn:evaluate -- you +must manually disable fallback processing by setting an empty value +for the refentry.manual.fallback.profile +parameter. + + + + diff --git a/xsl/params/refentry.manual.profile.xml b/xsl/params/refentry.manual.profile.xml new file mode 100644 index 000000000..33575f99f --- /dev/null +++ b/xsl/params/refentry.manual.profile.xml @@ -0,0 +1,67 @@ + + +refentry.manual.profile +string + + +refentry.manual.profile +Specifies profile for refentry "manual" data + + + + + + ($parentinfo/title + |../title)[1]/node() + + + + +Description + +The value of refentry.manual.profile is +a string representing an XPath expression. It is evaluated at +run-time and used only if +refentry.manual.profile.enabled is +non-zero. Otherwise, the refentry metadata-gathering logic +"hard coded" into the stylesheets is used. + +In man pages, this content is usually displayed in the middle of +the header of the page. The man(7) man page +describes this as "the title of the manual (e.g., Linux +Programmer's Manual)". Here are some examples from +existing man pages: + + + dpkg utilities + (dpkg-name) + + + User Contributed Perl Documentation + (GET) + + + GNU Development Tools + (ld) + + + Emperor Norton Utilities + (ddate) + + + Debian GNU/Linux manual + (faked) + + + GIMP Manual Pages + (gimp) + + + KDOC Documentation System + (qt2kdoc) + + + + + + diff --git a/xsl/params/refentry.source.fallback.profile.xml b/xsl/params/refentry.source.fallback.profile.xml new file mode 100644 index 000000000..d574ff575 --- /dev/null +++ b/xsl/params/refentry.source.fallback.profile.xml @@ -0,0 +1,44 @@ + + +refentry.source.fallback.profile +string + + +refentry.source.fallback.profile +Specifies profile of "fallback" for refentry "source" data + + + + + +refmeta/refmiscinfo[1]/node() + + + +Description + +The value of +refentry.source.fallback.profile is a string +representing an XPath expression. It is evaluated at run-time and used +only if no "source" data can be found by other means (that is, either +using the refentry metadata-gathering logic "hard coded" in +the stylesheets, or the value of the +refentry.source.name.profile and +refentry.version.profile parameters, if those +are enabled). + + +Depending on which XSLT engine you run, either the EXSLT +dyn:evaluate extension function (for xsltproc or +Xalan) or saxon:evaluate extension function (for +Saxon) are used to dynamically evaluate the value of +refentry.source.fallback.profile at +run-time. If you don't use xsltproc, Saxon, Xalan -- or some other +XSLT engine that supports dyn:evaluate -- you +must manually disable fallback processing by setting an empty value +for the refentry.source.fallback.profile +parameter. + + + + diff --git a/xsl/params/refentry.source.name.profile.xml b/xsl/params/refentry.source.name.profile.xml new file mode 100644 index 000000000..8252210c0 --- /dev/null +++ b/xsl/params/refentry.source.name.profile.xml @@ -0,0 +1,91 @@ + + +refentry.source.name.profile +string + + +refentry.source.name.profile +Specifies profile for refentry "source name" data + + + + + + ($info/productname + |$parentinfo/productname + |$info/orgname + |$parentinfo/orgname + |$info/corpname + |$parentinfo/corpname + |$info/corpcredit + |$parentinfo/corpcredit + |$info/corpauthor + |$parentinfo/corpauthor + |$info/author/orgname + |$parentinfo/author/orgname + |$info//publishername + |$parentinfo//publishername)[1]/node() + + + + +Description + +The value of refentry.source.name.profile +is a string representing an XPath expression. It is evaluated at +run-time and used only if +refentry.source.name.profile.enabled is +non-zero. Otherwise, the refentry metadata-gathering logic +"hard coded" into the stylesheets is used. + +A "source name" is one part of a (potentially) two-part +Name Version +"source" field. In man pages, it is usually displayed in the left +footer of the page. The man(7) man page describes +this as "the source of the command", and provides the following +examples: + + + For binaries, use something like: GNU, NET-2, SLS + Distribution, MCC Distribution. + + + For system calls, use the version of the kernel that you + are currently looking at: Linux 0.99.11. + + + For library calls, use the source of the function: GNU, BSD + 4.3, Linux DLL 4.4.1. + + + + +In practice, there are many pages that simply have a Version +number in the "source" field. So, it looks like what we have is a +two-part field, +Name Version, +where: + + + Name + + product name (e.g., BSD) or org. name (e.g., GNU) + + + + Version + + version number + + + +Each part is optional. If the Name is a +product name, then the Version is probably +the version of the product. Or there may be no +Name, in which case, if there is a +Version, it is probably the version +of the item itself, not the product it is part of. Or, if the +Name is an organization name, then there +probably will be no Version. + + diff --git a/xsl/params/refentry.source.name.suppress.xml b/xsl/params/refentry.source.name.suppress.xml index 00ba71acd..c5f873396 100644 --- a/xsl/params/refentry.source.name.suppress.xml +++ b/xsl/params/refentry.source.name.suppress.xml @@ -30,7 +30,7 @@ page -- then you might consider setting a non-zero value for Note that the terms "source", "source name", and "version" have special meanings in this context. For details, see the documentation -for the refentry.source.profile +for the refentry.source.name.profile parameter. diff --git a/xsl/params/refentry.version.profile.xml b/xsl/params/refentry.version.profile.xml new file mode 100644 index 000000000..b8e5a91a7 --- /dev/null +++ b/xsl/params/refentry.version.profile.xml @@ -0,0 +1,39 @@ + + +refentry.version.profile +string + + +refentry.version.profile +Specifies profile for refentry "version" data + + + + + + ($info/productnumber + |$parentinfo/productnumber + |$info/edition + |$parentinfo/edition + |$info/releaseinfo + |$parentinfo/releaseinfo)[1]/node() + + + + +Description + +The value of refentry.version.profile is +a string representing an XPath expression. It is evaluated at +run-time and used only if +refentry.version.profile.enabled is +non-zero. Otherwise, the refentry metadata-gathering logic +"hard coded" into the stylesheets is used. + +A "source.name" is one part of a (potentially) two-part +Name Version +"source" field. For more details, see the documentation for the +refentry.source.name.profile parameter. + + + diff --git a/xsl/params/refentry.version.suppress.xml b/xsl/params/refentry.version.suppress.xml index fd9cac495..1f447bd41 100644 --- a/xsl/params/refentry.version.suppress.xml +++ b/xsl/params/refentry.version.suppress.xml @@ -31,7 +31,7 @@ then you might consider setting a non-zero value for Note that the terms "source", "source name", and "version" have special meanings in this context. For details, see the documentation -for the refentry.source.profile +for the refentry.source.name.profile parameter. -- 2.40.0