forked from mirrors/nixpkgs
1d77dcaed3
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 |
||
|---|---|---|
| .. | ||
| administration | ||
| configuration | ||
| development | ||
| installation | ||
| release-notes | ||
| default.nix | ||
| man-configuration.xml | ||
| man-nixos-build-vms.xml | ||
| man-nixos-generate-config.xml | ||
| man-nixos-install.xml | ||
| man-nixos-option.xml | ||
| man-nixos-rebuild.xml | ||
| man-pages.xml | ||
| manual.xml | ||
| options-to-docbook.xsl | ||
| README | ||
| style.css | ||
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.