diff options
author | Graham Christensen <graham@grahamc.com> | 2018-09-02 16:08:06 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-09-02 16:08:06 -0400 |
commit | 14b04566864974ba1c9c35719502d1f5b290b102 (patch) | |
tree | edd8cdd9297fe32d13a22c3d5de9b6d99131aee6 | |
parent | 61deecdc34fc609d0f805b434101f3c8ae3b807a (diff) | |
parent | f865d0feabfafbb30a9e0659e19a30cb0dc24481 (diff) | |
download | nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.tar nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.tar.gz nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.tar.bz2 nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.tar.lz nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.tar.xz nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.tar.zst nixpkgs-14b04566864974ba1c9c35719502d1f5b290b102.zip |
Merge pull request #45930 from aszlig/option-description-parbreak
nixos: Split paras by \n\n in option descriptions
-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 be28c2c17af..aaa6e0da545 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 2038b0dff63..72ac89d4ff6 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 00000000000..1201c7612c2 --- /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> |