nixos: Split paras by \n\n in option descriptions #45930
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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
|
Looking ... |
Nice: I spot-checked the results with diffocsope, and everything looked good. Nicely done! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 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/>byoptions-to-docbook.xsl.The splitting itself is a bit more involved, because we can't simply split on every
\n\nbecause we'd also split text nodes of elements, for example:This would create one
<para/>element forone lineand another foranother 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>.Cc: @edolstra, @domenkozar