nixpkgs/nixos/doc/manual
aszlig f865d0feab
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
2018-09-02 08:10:37 +02:00
..
administration Document running nixos-rebuild switch to clear /boot space 2018-08-31 21:37:07 -04:00
configuration nixos docs: footnotes: give IDs 2018-09-01 16:24:37 -04:00
development nixos docs: Give sections IDs 2018-09-01 16:20:49 -04:00
installation nixos docs: Give sections IDs 2018-09-01 16:20:49 -04:00
release-notes xserver.displayManager: change default 2018-08-31 17:57:39 +02:00
.gitignore nixos docs: ignore generated files 2018-05-01 19:50:02 -04:00
default.nix nixos: Split paras by \n\n in option descriptions 2018-09-02 08:10:37 +02:00
Makefile makefile: auto-format xml docs outside of the doc subdir 2018-09-01 16:20:49 -04:00
man-configuration.xml nixos docs: format =) 2018-05-01 19:57:09 -04:00
man-nixos-build-vms.xml nixos/doc: ran make format 2018-05-31 21:03:51 -04:00
man-nixos-enter.xml nixos/doc: ran make format 2018-05-31 21:03:51 -04:00
man-nixos-generate-config.xml nixos/doc: ran make format 2018-05-31 21:03:51 -04:00
man-nixos-install.xml nixos/doc+man: Fixes squishedtogether definitions. 2018-05-31 21:07:15 -04:00
man-nixos-option.xml nixos/doc+man: Fixes squishedtogether definitions. 2018-05-31 21:07:15 -04:00
man-nixos-rebuild.xml nixos/doc+man: Fixes squishedtogether definitions. 2018-05-31 21:07:15 -04:00
man-nixos-version.xml nixos/doc: ran make format 2018-05-31 21:03:51 -04:00
man-pages.xml nixos docs: format =) 2018-05-01 19:57:09 -04:00
manual.xml nixos docs: give IDs to things 2018-09-01 16:20:49 -04:00
options-to-docbook.xsl nixos: Split paras by \n\n in option descriptions 2018-09-02 08:10:37 +02:00
postprocess-option-descriptions.xsl nixos: Split paras by \n\n in option descriptions 2018-09-02 08:10:37 +02:00
README nixos/doc/manual: Fix typos in README. 2014-07-23 15:00:25 +02:00
shell.nix doc: Adds xml fixing script. (see previous and next commits) 2018-05-31 21:02:15 -04:00

To build the manual, you need Nix installed on your system (no need
for NixOS). To install Nix, follow the instructions at

    https://nixos.org/nix/download.html

When you have Nix on your system, in the root directory of the project
(i.e., `nixpkgs`), run:

    nix-build nixos/release.nix -A manual.x86_64-linux

When this command successfully finishes, it will tell you where the
manual got generated.