nixpkgs/nixos/doc/manual
aszlig 1d77dcaed3
nixos/doc: Allow refs from options to the manual
My first attempt to do this was to just use a conditional <refsection/>
in order to not create exact references in the manpage but create the
reference in the HTML manual, as suggested by @edolstra on IRC.

Later I went on to use <olink/> to reference sections of the manual, but
in order to do that, we need to overhaul how we generate the manual and
manpages.

So, that's where we are now:

There is a new derivation called "manual-olinkdb", which is the olinkdb
for the HTML manual, which in turn creates the olinkdb.xml file and the
manual.db. The former contains the targetdoc references and the latter
the specific targetptr elements.

The reason why I included the olinkdb.xml verbatim is that first of all
the DTD is dependent on the Docbook XSL sources and the references
within the olinkdb.xml entities are relative to the current directory.

So using a store path for that would end up searching for the manual.db
directly in /nix/store/manual.db.

Unfortunately, the <olinks/> that end up in the output file are
relative, so for example if you're clicking on one of these within the
PDF, the URL is searched in the current directory.

However, the sections from the olink's text are still valid, so we could
use an alternative URL for that in the future.

The manual doesn't contain any links, so even referencing the relative
URL shouldn't do any harm.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Cc: @edolstra
2016-04-11 18:38:04 +02:00
..
administration nixos-manual: fix grammar 2015-12-10 19:17:33 +01:00
configuration nixos/taskserver: Add module documentation 2016-04-07 14:26:12 +02:00
development Revert "Add the tool "nixos-typecheck" that can check an option declaration to:" 2016-03-01 20:52:06 +01:00
installation nixos manual: recommend use of dd for writing the image 2016-04-02 17:41:38 +02:00
release-notes Fix typo in service.syncthing.dataDir description. 2016-04-03 17:36:38 +00:00
default.nix nixos/doc: Allow refs from options to the manual 2016-04-11 18:38:04 +02:00
man-configuration.xml Move all of NixOS to nixos/ in preparation of the repository merge 2013-10-10 13:28:20 +02:00
man-nixos-build-vms.xml Move all of NixOS to nixos/ in preparation of the repository merge 2013-10-10 13:28:20 +02:00
man-nixos-generate-config.xml filesystems: use list of strings for fs options 2016-02-06 19:48:30 +00:00
man-nixos-install.xml nixos-install: support -j, --cores and --option. Closes #6755 2015-03-11 16:47:44 +00:00
man-nixos-option.xml nixos-option: fixes as suggested by @nbp 2014-09-06 20:59:14 +02:00
man-nixos-rebuild.xml nixos-rebuild: Document --build-host and --target-host options 2016-01-01 18:22:11 +01:00
man-pages.xml document options to nixos-install script 2015-01-06 14:49:24 +01:00
manual.xml Move release notes to an appendix and a separate chunk 2015-07-22 16:21:32 +02:00
options-to-docbook.xsl Manual: Don't render types as strings 2015-07-30 13:44:54 +02:00
README nixos/doc/manual: Fix typos in README. 2014-07-23 15:00:25 +02:00
style.css Manual: Chunk into separate pages 2014-08-25 19:08:31 +02: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.