diff options
author | aszlig <aszlig@nix.build> | 2018-09-02 05:05:34 +0200 |
---|---|---|
committer | aszlig <aszlig@nix.build> | 2018-09-02 08:10:37 +0200 |
commit | f865d0feabfafbb30a9e0659e19a30cb0dc24481 (patch) | |
tree | 055ebffbbe00dc1b0169e16f22391d4cbd28ff57 /nixos/doc | |
parent | 953b77f07be3c1fdef3552ee98c5d26accdde4c1 (diff) |
nixos: Split paras by \n\n in option descriptions
What annoyed me for a long time was the fact, that in order to break into a new paragraph, you need to insert </para><para> in the description attribute of an option. Now we will automatically create <para/> elements for every block that is separated by two consecutive newlines. I first tried to do this within options-to-docbook.xsl, but it turns out[1] that this isn't directly possible with XSLT 1.0, so I added another XSLT file that postprocesses the option descriptions that are now enclosed in <nixos:option-description/> by options-to-docbook.xsl. The splitting itself is a bit more involved, because we can't simply split on every \n\n because we'd also split text nodes of elements, for example: <screen><![CDATA[ one line another one ]]></screen> This would create one <para/> element for "one line" and another for "another line", which we obviously don't want because <screen/> is used to display verbatim contents of what a user is seeing on the screen. So what we do instead is splitting *only* the top-level text nodes within the outermost <para/> and leave all elements as-is. If there are more than one <para/> elements at the top-level, we simply don't process it at all, because the description then already contains </para><para>. https://www.mhonarc.org/archive/html/xsl-list/2012-09/msg00319.html Signed-off-by: aszlig <aszlig@nix.build> Cc: @edolstra, @domenkozar
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/default.nix | 4 | ||||
-rw-r--r-- | nixos/doc/manual/options-to-docbook.xsl | 11 | ||||
-rw-r--r-- | nixos/doc/manual/postprocess-option-descriptions.xsl | 115 |
3 files changed, 125 insertions, 5 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index be28c2c17afd8..aaa6e0da545f9 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -90,7 +90,9 @@ let fi ${buildPackages.libxslt.bin}/bin/xsltproc \ --stringparam revision '${revision}' \ - -o $out ${./options-to-docbook.xsl} $optionsXML + -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML + ${buildPackages.libxslt.bin}/bin/xsltproc \ + -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml ''; sources = lib.sourceFilesBySuffices ./. [".xml"]; diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl index 2038b0dff63ee..72ac89d4ff62c 100644 --- a/nixos/doc/manual/options-to-docbook.xsl +++ b/nixos/doc/manual/options-to-docbook.xsl @@ -4,6 +4,7 @@ xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:str="http://exslt.org/strings" xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:nixos="tag:nixos.org" xmlns="http://docbook.org/ns/docbook" extension-element-prefixes="str" > @@ -30,10 +31,12 @@ <listitem> - <para> - <xsl:value-of disable-output-escaping="yes" - select="attr[@name = 'description']/string/@value" /> - </para> + <nixos:option-description> + <para> + <xsl:value-of disable-output-escaping="yes" + select="attr[@name = 'description']/string/@value" /> + </para> + </nixos:option-description> <xsl:if test="attr[@name = 'type']"> <para> diff --git a/nixos/doc/manual/postprocess-option-descriptions.xsl b/nixos/doc/manual/postprocess-option-descriptions.xsl new file mode 100644 index 0000000000000..1201c7612c2ed --- /dev/null +++ b/nixos/doc/manual/postprocess-option-descriptions.xsl @@ -0,0 +1,115 @@ +<?xml version="1.0"?> + +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://exslt.org/strings" + xmlns:exsl="http://exslt.org/common" + xmlns:db="http://docbook.org/ns/docbook" + xmlns:nixos="tag:nixos.org" + extension-element-prefixes="str exsl"> + <xsl:output method='xml' encoding="UTF-8" /> + + <xsl:template match="@*|node()"> + <xsl:copy> + <xsl:apply-templates select="@*|node()" /> + </xsl:copy> + </xsl:template> + + <xsl:template name="break-up-description"> + <xsl:param name="input" /> + <xsl:param name="buffer" /> + + <!-- Every time we have two newlines following each other, we want to + break it into </para><para>. --> + <xsl:variable name="parbreak" select="'

'" /> + + <!-- Similar to "(head:tail) = input" in Haskell. --> + <xsl:variable name="head" select="$input[1]" /> + <xsl:variable name="tail" select="$input[position() > 1]" /> + + <xsl:choose> + <xsl:when test="$head/self::text() and contains($head, $parbreak)"> + <!-- If the haystack provided to str:split() directly starts or + ends with $parbreak, it doesn't generate a <token/> for that, + so we are doing this here. --> + <xsl:variable name="splitted-raw"> + <xsl:if test="starts-with($head, $parbreak)"><token /></xsl:if> + <xsl:for-each select="str:split($head, $parbreak)"> + <token><xsl:value-of select="node()" /></token> + </xsl:for-each> + <!-- Something like ends-with($head, $parbreak), but there is + no ends-with() in XSLT, so we need to use substring(). --> + <xsl:if test=" + substring($head, string-length($head) - + string-length($parbreak) + 1) = $parbreak + "><token /></xsl:if> + </xsl:variable> + <xsl:variable name="splitted" + select="exsl:node-set($splitted-raw)/token" /> + <!-- The buffer we had so far didn't contain any text nodes that + contain a $parbreak, so we can put the buffer along with the + first token of $splitted into a para element. --> + <para xmlns="http://docbook.org/ns/docbook"> + <xsl:apply-templates select="exsl:node-set($buffer)" /> + <xsl:apply-templates select="$splitted[1]/node()" /> + </para> + <!-- We have already emitted the first splitted result, so the + last result is going to be set as the new $buffer later + because its contents may not be directly followed up by a + $parbreak. --> + <xsl:for-each select="$splitted[position() > 1 + and position() < last()]"> + <para xmlns="http://docbook.org/ns/docbook"> + <xsl:apply-templates select="node()" /> + </para> + </xsl:for-each> + <xsl:call-template name="break-up-description"> + <xsl:with-param name="input" select="$tail" /> + <xsl:with-param name="buffer" select="$splitted[last()]/node()" /> + </xsl:call-template> + </xsl:when> + <!-- Either non-text node or one without $parbreak, which we just + want to buffer and continue recursing. --> + <xsl:when test="$input"> + <xsl:call-template name="break-up-description"> + <xsl:with-param name="input" select="$tail" /> + <!-- This essentially appends $head to $buffer. --> + <xsl:with-param name="buffer"> + <xsl:if test="$buffer"> + <xsl:for-each select="exsl:node-set($buffer)"> + <xsl:apply-templates select="." /> + </xsl:for-each> + </xsl:if> + <xsl:apply-templates select="$head" /> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <!-- No more $input, just put the remaining $buffer in a para. --> + <xsl:otherwise> + <para xmlns="http://docbook.org/ns/docbook"> + <xsl:apply-templates select="exsl:node-set($buffer)" /> + </para> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="nixos:option-description"> + <xsl:choose> + <!-- + Only process nodes that are comprised of a single <para/> element, + because if that's not the case the description already contains + </para><para> in between and we need no further processing. + --> + <xsl:when test="count(db:para) > 1"> + <xsl:apply-templates select="node()" /> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="break-up-description"> + <xsl:with-param name="input" + select="exsl:node-set(db:para/node())" /> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + +</xsl:stylesheet> |