<!ENTITY refentry.version.profile.enabled SYSTEM "../params/refentry.version.profile.enabled.xml">
<!ENTITY refentry.source.name.suppress SYSTEM "../params/refentry.source.name.suppress.xml">
<!ENTITY refentry.version.suppress SYSTEM "../params/refentry.version.suppress.xml">
+<!ENTITY refentry.date.profile SYSTEM "../params/refentry.date.profile.xml">
+<!ENTITY refentry.manual.fallback.profile SYSTEM "../params/refentry.manual.fallback.profile.xml">
+<!ENTITY refentry.manual.profile SYSTEM "../params/refentry.manual.profile.xml">
+<!ENTITY refentry.source.fallback.profile SYSTEM "../params/refentry.source.fallback.profile.xml">
+<!ENTITY refentry.source.name.profile SYSTEM "../params/refentry.source.name.profile.xml">
+<!ENTITY refentry.version.profile SYSTEM "../params/refentry.version.profile.xml">
</reference>
<reference id="charmap">
<title>Refentry metadata gathering</title>
+&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;
</reference>
<appendix id="stylesheet">
<title>The Stylesheet</title>
<src:fragref linkend="refentry.version.profile.enabled.frag"/>
<src:fragref linkend="refentry.source.name.suppress.frag"/>
<src:fragref linkend="refentry.version.suppress.frag"/>
+<src:fragref linkend="refentry.date.profile.frag"/>
+<src:fragref linkend="refentry.manual.fallback.profile.frag"/>
+<src:fragref linkend="refentry.manual.profile.frag"/>
+<src:fragref linkend="refentry.source.fallback.profile.frag"/>
+<src:fragref linkend="refentry.source.name.profile.frag"/>
+<src:fragref linkend="refentry.version.profile.frag"/>
</xsl:stylesheet>
</src:fragment>
--- /dev/null
+<refentry id="refentry.date.profile">
+<refmeta>
+<refentrytitle>refentry.date.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>refentry.date.profile</refname>
+<refpurpose>Specifies profile for refentry "date" data</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='refentry.date.profile.frag'>
+<xsl:param name="refentry.date.profile">
+ ($info/date
+ |$info/pubdate
+ |$parentinfo/date
+ |$parentinfo/pubdate)[1]/node()
+</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of <parameter>refentry.date.profile</parameter> is a
+string representing an XPath expression. It is evaluated at run-time
+and used only if <parameter>refentry.date.profile.enabled</parameter>
+is non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering
+logic "hard coded" into the stylesheets is used.</para>
+
+<para> The <literal>man(7)</literal> 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.</para>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="refentry.manual.fallback.profile">
+<refmeta>
+<refentrytitle>refentry.manual.fallback.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>refentry.manual.fallback.profile</refname>
+<refpurpose>Specifies profile of "fallback" for refentry "manual" data</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='refentry.manual.fallback.profile.frag'>
+<xsl:param name="refentry.manual.fallback.profile">
+refmeta/refmiscinfo[1]/node()</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of
+<parameter>refentry.manual.fallback.profile</parameter> 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 <tag>refentry</tag> metadata-gathering logic "hard
+coded" in the stylesheets, or the value of
+<parameter>refentry.manual.profile</parameter>, if it is
+enabled).</para>
+
+<important>
+<para>Depending on which XSLT engine you run, either the EXSLT
+<function>dyn:evaluate</function> extension function (for xsltproc or
+Xalan) or <function>saxon:evaluate</function> extension function (for
+Saxon) are used to dynamically evaluate the value of
+<parameter>refentry.manual.fallback.profile</parameter> at
+run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
+XSLT engine that supports <function>dyn:evaluate</function> -- you
+must manually disable fallback processing by setting an empty value
+for the <parameter>refentry.manual.fallback.profile</parameter>
+parameter.</para>
+</important>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="refentry.manual.profile">
+<refmeta>
+<refentrytitle>refentry.manual.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>refentry.manual.profile</refname>
+<refpurpose>Specifies profile for refentry "manual" data</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='refentry.manual.profile.frag'>
+<xsl:param name="refentry.manual.profile">
+ ($parentinfo/title
+ |../title)[1]/node()
+</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of <parameter>refentry.manual.profile</parameter> is
+a string representing an XPath expression. It is evaluated at
+run-time and used only if
+<parameter>refentry.manual.profile.enabled</parameter> is
+non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
+"hard coded" into the stylesheets is used.</para>
+
+<para>In man pages, this content is usually displayed in the middle of
+the header of the page. The <literal>man(7)</literal> man page
+describes this as "the title of the manual (e.g., <citetitle>Linux
+Programmer's Manual</citetitle>)". Here are some examples from
+existing man pages:
+<itemizedlist>
+ <listitem>
+ <para><citetitle>dpkg utilities</citetitle>
+ (<command>dpkg-name</command>)</para>
+ </listitem>
+ <listitem>
+ <para><citetitle>User Contributed Perl Documentation</citetitle>
+ (<command>GET</command>)</para>
+ </listitem>
+ <listitem>
+ <para><citetitle>GNU Development Tools</citetitle>
+ (<command>ld</command>)</para>
+ </listitem>
+ <listitem>
+ <para><citetitle>Emperor Norton Utilities</citetitle>
+ (<command>ddate</command>)</para>
+ </listitem>
+ <listitem>
+ <para><citetitle>Debian GNU/Linux manual</citetitle>
+ (<command>faked</command>)</para>
+ </listitem>
+ <listitem>
+ <para><citetitle>GIMP Manual Pages</citetitle>
+ (<command>gimp</command>)</para>
+ </listitem>
+ <listitem>
+ <para><citetitle>KDOC Documentation System</citetitle>
+ (<command>qt2kdoc</command>)</para>
+ </listitem>
+</itemizedlist>
+</para>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="refentry.source.fallback.profile">
+<refmeta>
+<refentrytitle>refentry.source.fallback.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>refentry.source.fallback.profile</refname>
+<refpurpose>Specifies profile of "fallback" for refentry "source" data</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='refentry.source.fallback.profile.frag'>
+<xsl:param name="refentry.source.fallback.profile">
+refmeta/refmiscinfo[1]/node()</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of
+<parameter>refentry.source.fallback.profile</parameter> 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 <tag>refentry</tag> metadata-gathering logic "hard coded" in
+the stylesheets, or the value of the
+<parameter>refentry.source.name.profile</parameter> and
+<parameter>refentry.version.profile</parameter> parameters, if those
+are enabled).</para>
+
+<important>
+<para>Depending on which XSLT engine you run, either the EXSLT
+<function>dyn:evaluate</function> extension function (for xsltproc or
+Xalan) or <function>saxon:evaluate</function> extension function (for
+Saxon) are used to dynamically evaluate the value of
+<parameter>refentry.source.fallback.profile</parameter> at
+run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
+XSLT engine that supports <function>dyn:evaluate</function> -- you
+must manually disable fallback processing by setting an empty value
+for the <parameter>refentry.source.fallback.profile</parameter>
+parameter.</para>
+</important>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="refentry.source.name.profile">
+<refmeta>
+<refentrytitle>refentry.source.name.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>refentry.source.name.profile</refname>
+<refpurpose>Specifies profile for refentry "source name" data</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='refentry.source.name.profile.frag'>
+<xsl:param name="refentry.source.name.profile">
+ ($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()
+</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of <parameter>refentry.source.name.profile</parameter>
+is a string representing an XPath expression. It is evaluated at
+run-time and used only if
+<parameter>refentry.source.name.profile.enabled</parameter> is
+non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
+"hard coded" into the stylesheets is used.</para>
+
+<para>A "source name" is one part of a (potentially) two-part
+<replaceable>Name</replaceable> <replaceable>Version</replaceable>
+"source" field. In man pages, it is usually displayed in the left
+footer of the page. The <literal>man(7)</literal> man page describes
+this as "the source of the command", and provides the following
+examples:
+<itemizedlist>
+ <listitem>
+ <para>For binaries, use something like: GNU, NET-2, SLS
+ Distribution, MCC Distribution.</para>
+ </listitem>
+ <listitem>
+ <para>For system calls, use the version of the kernel that you
+ are currently looking at: Linux 0.99.11.</para>
+ </listitem>
+ <listitem>
+ <para>For library calls, use the source of the function: GNU, BSD
+ 4.3, Linux DLL 4.4.1.</para>
+ </listitem>
+</itemizedlist>
+</para>
+
+<para>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,
+<replaceable>Name</replaceable> <replaceable>Version</replaceable>,
+where:
+<variablelist>
+ <varlistentry>
+ <term>Name</term>
+ <listitem>
+ <para>product name (e.g., BSD) or org. name (e.g., GNU)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Version</term>
+ <listitem>
+ <para>version number</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+Each part is optional. If the <replaceable>Name</replaceable> is a
+product name, then the <replaceable>Version</replaceable> is probably
+the version of the product. Or there may be no
+<replaceable>Name</replaceable>, in which case, if there is a
+<replaceable>Version</replaceable>, it is probably the version
+of the item itself, not the product it is part of. Or, if the
+<replaceable>Name</replaceable> is an organization name, then there
+probably will be no <replaceable>Version</replaceable>.</para>
+</refsect1>
+</refentry>
<para>Note that the terms "source", "source name", and "version" have
special meanings in this context. For details, see the documentation
-for the <parameter>refentry.source.profile</parameter>
+for the <parameter>refentry.source.name.profile</parameter>
parameter.</para>
</refsect1>
--- /dev/null
+<refentry id="refentry.version.profile">
+<refmeta>
+<refentrytitle>refentry.version.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>refentry.version.profile</refname>
+<refpurpose>Specifies profile for refentry "version" data</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='refentry.version.profile.frag'>
+<xsl:param name="refentry.version.profile">
+ ($info/productnumber
+ |$parentinfo/productnumber
+ |$info/edition
+ |$parentinfo/edition
+ |$info/releaseinfo
+ |$parentinfo/releaseinfo)[1]/node()
+</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of <parameter>refentry.version.profile</parameter> is
+a string representing an XPath expression. It is evaluated at
+run-time and used only if
+<parameter>refentry.version.profile.enabled</parameter> is
+non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
+"hard coded" into the stylesheets is used.</para>
+
+<para>A "source.name" is one part of a (potentially) two-part
+<replaceable>Name</replaceable> <replaceable>Version</replaceable>
+"source" field. For more details, see the documentation for the
+<parameter>refentry.source.name.profile</parameter> parameter.</para>
+
+</refsect1>
+</refentry>
<para>Note that the terms "source", "source name", and "version" have
special meanings in this context. For details, see the documentation
-for the <parameter>refentry.source.profile</parameter>
+for the <parameter>refentry.source.name.profile</parameter>
parameter.</para>
</refsect1>
projects / docbook-dsssl / commitdiff