a few things should've used buildPackages/nativeBuildInputs to not not require
the host architecture for building docs. tested by building aarch64-linux docs
on x86_64-linux, and the result looks good.
this partially solves the problem of "missing description" warnings of the
options doc build being lost by nix build, at the cost of failing builds that
previously ran. an option to disable this behaviour is provided.
most modules can be evaluated for their documentation in a very
restricted environment that doesn't include all of nixpkgs. this
evaluation can then be cached and reused for subsequent builds, merging
only documentation that has changed into the cached set. since nixos
ships with a large number of modules of which only a few are used in any
given config this can save evaluation a huge percentage of nixos
options available in any given config.
in tests of this caching, despite having to copy most of nixos/, saves
about 80% of the time needed to build the system manual, or about two
second on the machine used for testing. build time for a full system
config shrank from 9.4s to 7.4s, while turning documentation off
entirely shortened the build to 7.1s.
Motivation is to support other repositories containing nixos
modules that would like to generate options documentation:
- nix-darwin
- private repos
- arion
- ??
Because when I see "config.system.build.manual.manual" after I forgot
what it means I ask "Why do I need that second `.manual` there again?".
Doesn't happen with `config.system.build.manual.manualHTML`.
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
This makes the command ‘nix-env -qa -f. --arg config '{skipAliases =
true;}'’ work in Nixpkgs.
Misc...
- qtikz: use libsForQt5.callPackage
This ensures we get the right poppler.
- rewrites:
docbook5_xsl -> docbook_xsl_ns
docbook_xml_xslt -> docbook_xsl
diffpdf: fixup
- Rectifies diverging CSS by combining
nixos/nixpkgs docs CSS
- Moves our custom Highlight.js loader in to
the hljs package
- Switches the nixos docs to use SVG
callouts too
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.
Among other things, this will allow *2nix tools to output plain data
while still being composable with the traditional
callPackage/.override interfaces.
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.
Previously only the line numbers of a giant, internally generated XML file were
printed, without any kind of debuggability.
Now at least the mentioned lines are printed with a little bit of surrounding
context (to have something to grep for).
```
manual-combined.xml:4863: element para: Relax-NG validity error : Did not expect element para there
4859 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-writing-modules">
4860
4861 <title>Writing NixOS Modules</title>
4862
4863 <para>NixOS has a modular system for declarative configuration. This
4864 system combines multiple <emphasis>modules</emphasis> to produce the
4865 full system configuration. One of the modules that constitute the
```
In light of Emacs packaging improvements such as those mentioned
in #11503, and with the addition of a systemd service (#15807
and #16356), and considering that the wiki page is completely
out of date (#13217), it seems that some documentation is in order.
* Hydra doesn't like spaces in filenames.
* The zip file contained nix/store/.../OEBPS rather than OEBPS at
top-level, causing some programs (like okular) to barf.
* Remove the redundant $dst/epub directory.
This allows to use <olink> tags inside NixOS options to reference
sections from the manual. I've originally introduced it in #14476 to
reference the Taskserver specific documentation from the options
reference but as suggested by @nbp, this was done as a separate pull
request to ensure greater visibility rather than being "hidden" in the
Taskserver branch.
The build time for the manual is around 30s on my machine without this
change and 34s with this change, so it shouldn't have a very big impact
on the build time of the manual.
Olinks between the options reference and the manual now will look like
this:
"More instructions about NixOS in conjuction with Taskserver can be
found in the NixOS manual at Chapter 15, Taskserver."
More documentation about olinks can be found here:
http://www.sagehill.net/docbookxsl/Olinking.html
Acked-by: Eelco Dolstra <eelco.dolstra@logicblox.com>
This adds a Taskserver module along with documentation and a small
helper tool which eases managing a custom CA along with Taskserver
organisations, users and groups.
Taskserver is the server component of Taskwarrior, a TODO list
application for the command line.
The work has been started by @matthiasbeyer back in mid 2015 and I have
continued to work on it recently, so this merge contains commits from
both of us.
Thanks particularly to @nbp and @matthiasbeyer for reviewing and
suggesting improvements.
I've tested this with the new test (nixos/tests/taskserver.nix) this
branch adds and it fails because of the changes introduced by the
closure-size branch, so we need to do additional work on base of this.
This reverts commit 1d77dcaed3.
It will be reintroduced along with #14700 as a separate branch, as
suggested by @nbp.
I added this to this branch because I thought it was a necessary
dependency, but it turns out that the build of the manual/manpages still
succeeds and merely prints a warning like this:
warning: failed to load external entity "olinkdb.xml"
Olink error: could not open target database 'olinkdb.xml'.
Error: unresolved olink: targetdoc/targetptr = 'manual/module-taskserver'.
The olink itself will be replaced by "???", so users looking at the
description of the option in question will still see the reference to
the NixOS manual, like this:
More instructions about NixOS in conjuction with Taskserver can be found
in the NixOS manual at ???.
Signed-off-by: aszlig <aszlig@redmoonstudios.org>
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
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
It's not by any means exhaustive, but we're still going to change the
implementation, so let's just use this as a starting point.
Signed-off-by: aszlig <aszlig@redmoonstudios.org>
