On Tue, 17 Jan 2023 19:13:38 +0100 Brar Piening <b...@gmx.de> wrote: > On 17.01.2023 at 14:12, Karl O. Pinc wrote: > > If you're not willing to try I am willing to see if I can > > produce an example to work from. My XSLT is starting to > > come back. > > I'm certainly willing to try but I'd appreciate an example in any > case.
It's good you asked. After poking about the XSLT 1.0 spec to refresh my memory I abandoned the "mode" approach entirely. The real "right way" is to use the import mechanism. I've attached a patch that "wraps" the section.heading template and adds extra stuff to the HTML output generated by the stock template. (example_section_heading_override.patch) There's a bug. All that goes into the html is a comment, not a hoverable link. But the technique is clear. On my system (Debian 11, bullseye) I found the URI to import by looking at: /usr/share/xml/docbook/stylesheet/docbook-xsl/catalog.xml (Which is probably the right place to look.) Ultimately, that file is findable via: /etc/xml/catalog The "best way" on Debian is: /usr/share/doc/docbook-xsl/README.gz In other words, the README that comes with the style sheets. Supposedly, the href=URLs are really URIs and will be good no matter what/when. The XSLT processor should know to look at the system catalogs and read the imported style sheet from the local file system. It might be useful to add --nonet to the xsltproc invocation(s) in the Makefile(s). Just in case; to keep from retrieving stylesheets from the net. (If the option is not already there. I didn't look.) If this is the first time that PG uses the XSLT import mechanism I imagine that "things could go wrong" depending on what sort of system is being used to build the docs. I'm not worried, but it is something to note for the committer. > My XSLT skills are mostly learning by doing combined with trial and > error. I think of XSLT as a functional programming language. Recursion is a big deal, and data directed programming can be a powerful technique because XSLT is so good with data structures. (https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/6515/sicp.zip/full-text/book/book-Z-H-17.html#%_sec_2.4.3) Regards, Karl <k...@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl index 9df2782ce4..88e084e190 100644 --- a/doc/src/sgml/stylesheet-html-common.xsl +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -12,6 +12,10 @@ all HTML output variants (chunked and single-page). --> +<!-- Imports - to override stylesheet templates --> +<xsl:import + href="http://cdn.docbook.org/release/xsl/current/html/sections.xsl"/> + <!-- Parameters --> <xsl:param name="make.valid.html" select="1"></xsl:param> <xsl:param name="generate.id.attributes" select="1"></xsl:param> @@ -301,4 +305,53 @@ set toc,title </xsl:choose> </xsl:template> +<!-- Override the standard section heading generation to add an id link --> +<xsl:template name="section.heading"> + <xsl:param name="section" select="."/> + <xsl:param name="level" select="1"/> + <xsl:param name="allow-anchors" select="1"/> + <xsl:param name="title"/> + <xsl:param name="class" select="'title'"/> + <xsl:apply-imports/> + <xsl:call-template name="pg.id.link"> + <xsl:with-param name="object" select="$section"/> + </xsl:call-template> +</xsl:template> + +<!-- Creates a link pointing to an id within the document --> +<xsl:template name="pg.id.link"> + <xsl:param name="object" select="."/> + <xsl:choose> + <xsl:when test="$object/@id or $object/@xml:id"> + <a> + <xsl:attribute name="href"> + <xsl:text>#</xsl:text> + <xsl:call-template name="object.id"> + <xsl:with-param name="object" select="$object"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="class"> + <xsl:text>id_link</xsl:text> + </xsl:attribute> + <xsl:text> #</xsl:text> + </a> + </xsl:when> + <xsl:otherwise> + <!-- Only complain about varlistentries if at least one entry in the list has an id --> + <xsl:if test="name($object) != 'varlistentry' or $object/parent::variablelist/varlistentry[@id]"> + <xsl:message terminate="no"> + <xsl:value-of select ="name($object)"/> + <xsl:text> element without id. Please add an id to make it usable</xsl:text> + <xsl:text> as stable anchor in the public HTML documentation.</xsl:text> + </xsl:message> + <xsl:comment> + <xsl:text>Please add an id to the </xsl:text> + <xsl:value-of select ="name($object)"/> + <xsl:text> element in the sgml source code.</xsl:text> + </xsl:comment> + </xsl:if> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + </xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css index 6410a47958..e4174e0613 100644 --- a/doc/src/sgml/stylesheet.css +++ b/doc/src/sgml/stylesheet.css @@ -163,3 +163,13 @@ acronym { font-style: inherit; } width: 75%; } } + +/* Links to ids of headers and definition terms */ +a.id_link { + color: inherit; + visibility: hidden; +} + +*:hover > a.id_link { + visibility: visible; +}
