Commit graph

24 commits

Author SHA1 Message Date
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
Graham Christensen 34d2ec7c09
nixos docs: give IDs to things 2018-09-01 16:20:49 -04:00
Graham Christensen 0ff0d138e4
nixos docs: Add a makefile for hacking on the nixos docs 2018-04-28 04:00:55 -04:00
Jan Malakhovski 660806066a nixos, lib: implement relatedPackages option
This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.

See the next several commits for examples.
2018-02-09 19:51:06 +00:00
Graham Christensen b5a61f2c59
Revert "nixos: doc: implement related packages in the manual" 2017-12-23 07:19:45 -05:00
Jan Malakhovski 67ec6371d5 nixos, lib: implement relatedPackages option
This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.
2017-12-07 21:26:35 +00:00
Domen Kožar 5260686aa8 fix https://github.com/NixOS/nixops/issues/331 2016-06-03 15:55:17 +01:00
Eelco Dolstra bb9aff2f0c Manual: Don't render types as strings 2015-07-30 13:44:54 +02:00
Eelco Dolstra f463d24903 Add read-only options
These are options that can have only one definition, regardless of
priority.
2015-07-30 13:44:50 +02:00
Eelco Dolstra d61e1b24e6 Fix indentation 2015-07-30 13:44:47 +02:00
Domen Kožar 79a51b0cf3 Add Type information into manual and manpages, fixes #4600 2015-01-04 15:41:32 +01:00
Eelco Dolstra 80a3c883a9 Manual: Render function defaults 2014-08-09 16:33:01 +02:00
Eelco Dolstra 30d0864dc6 Simplify 2014-04-14 10:26:12 +02:00
Eelco Dolstra ba29614578 Manual: Generate stable ids for options
E.g. ‘#opt-boot.initrd.kernelModules’.

Also, shut up a stupid XSLT warning (‘attribute value is not an NCName’).
2014-04-14 10:26:12 +02:00
Domen Kozar 8e1d765f61 nixos manual: make nixos options linkable 2014-03-08 19:34:28 +01:00
Eelco Dolstra be5d3a59dd Clean up some option examples 2013-10-30 18:47:43 +01:00
Eelco Dolstra 0695b68c8c Manual: Render multi-line strings properly 2013-10-29 17:39:31 +01:00
Eelco Dolstra bfaa6b7352 Manual: Escape $ 2013-10-29 17:39:31 +01:00
Eelco Dolstra 60c4c468f1 Manual: Render strings containing special characters as indented strings 2013-10-29 17:39:31 +01:00
Eelco Dolstra b64f43cdbd Manual: Don't show "Default: none" 2013-10-29 17:39:31 +01:00
Eelco Dolstra c407db6316 Manual: Render null values 2013-10-29 16:18:23 +01:00
Eelco Dolstra fad83a9560 Allow literalExample in subexpressions of examples 2013-10-23 20:08:22 +02:00
Eelco Dolstra 0def73f390 Manual: Don't depend on the absolute path of modules
This ensures that the manual has the same store path regardless of the
directory in which Nixpkgs is stored, and thus can be fetched from the
channel.
2013-10-23 20:08:22 +02:00
Eelco Dolstra 5c1f8cbc70 Move all of NixOS to nixos/ in preparation of the repository merge 2013-10-10 13:28:20 +02:00
Renamed from doc/manual/options-to-docbook.xsl (Browse further)