Commit graph

82 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
Matthew Bauer
76999cc40e treewide: remove aliases in nixpkgs
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
2018-07-18 23:25:20 -04:00
Jan Malakhovski
2a5688574c nixos: doc: make relatedPackages a bit smarter 2018-06-13 16:25:10 +00:00
Graham Christensen
0ff0d138e4
nixos docs: Add a makefile for hacking on the nixos docs 2018-04-28 04:00:55 -04:00
Graham Christensen
59f8b1e844
nixos docs: Move generated XML in to a specific subdirectory to allow easier hacking 2018-04-27 22:44:51 -04:00
Graham Christensen
8f33464ca7
nixos docs: syntax highlight
- 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
2018-04-05 07:54:01 -04:00
Tuomas Tynkkynen
3918182cb5 nixos/manual: Don't depend on non-bin outputs of libxml2 and libxslt
Might fix https://hydra.nixos.org/build/71580290.
2018-03-21 22:18:49 +02:00
Shea Levy
20072d733b
nixos: manual: Fix cross-compilation. 2018-03-01 10:41:50 -05:00
Jan Malakhovski
810c4702cf stdenv.mkDerivation: rename meta.evaluates -> meta.available
A much better name.
2018-02-18 13:33:25 +00:00
Jan Malakhovski
b468f98b02 nixos: doc: trivial cleanup and docstring fix 2018-02-11 22:41:06 +00:00
Jan Malakhovski
252ec7da0a nixos: doc: make option sorting somewhat more efficient 2018-02-11 22:07:11 +00: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
Jan Malakhovski
a7d75ab648 nixos/doc: push all the enable*' and package*` options to the top of their option group
Why? Because this way configuration.nix(5) can be read linearly.

Before:

> virtualisation.xen.bootParams
> ...
> virtualisation.xen.enable
> ...
> virtualisation.xen.package
> ...

After:

> virtualisation.xen.enable
> virtualisation.xen.package
> virtualisation.xen.bootParams
> ...
2018-02-09 19:51:05 +00:00
Shea Levy
943592f698
Add setFunctionArgs lib function.
Among other things, this will allow *2nix tools to output plain data
while still being composable with the traditional
callPackage/.override interfaces.
2018-01-31 14:02:19 -05: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
Jan Malakhovski
182463dc79 nixos/doc: push all the enable*' and package*` options to the top of their option group
Why? Because this way configuration.nix(5) can be read linearly.

Before:

> virtualisation.xen.bootParams
> ...
> virtualisation.xen.enable
> ...
> virtualisation.xen.package
> ...

After:

> virtualisation.xen.enable
> virtualisation.xen.package
> virtualisation.xen.bootParams
> ...
2017-12-07 21:26:34 +00:00
Profpatsch
f09f49d483 nixos/doc/manual: print context on failing xmllint validation
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
```
2017-11-22 21:27:05 +01:00
Graham Christensen
1eb979db0e
nixos manual: combine XML and validate separately 2017-06-29 11:25:03 -04:00
Graham Christensen
4f3f926906
nixos manual: Remove trailing newline in version XML 2017-06-28 19:58:06 -04:00
Eelco Dolstra
75a1ec8a65 NixOS: Use runCommand instead of mkDerivation in a few places 2016-09-29 13:05:28 +02:00
Eric Sagnes
b50e627ef6 nixos manual: cleanup generation 2016-08-30 09:40:05 +09:00
Eric Sagnes
898435d16e manual: automatically generate modules entries 2016-08-11 00:24:41 +09:00
Rodney Lorrimar
6711e62d51 nixos manual: add Emacs section (fixes #13217)
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.
2016-08-02 11:17:52 +01:00
Eelco Dolstra
0804f67024 Fix epub generation
* 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.
2016-08-01 11:10:22 +02:00
Eelco Dolstra
d5756cdf0a Remove the PDF manual
PDF is very 20th century and nobody reads technical documentation this
way anymore.
2016-08-01 11:10:21 +02:00
Christine Koppelt
39da575262 add epub for NixOS manual (second try) (#17205) 2016-07-28 04:27:39 +02:00
aszlig
d2c64031a0
Merge pull request #14700: olinks for NixOS manual
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>
2016-05-02 11:01:13 +02:00
aszlig
9ed9e268a2
Merge pull request #14476 (taskserver)
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.
2016-04-15 00:21:49 +02:00
aszlig
c36d6e5964
nixos/doc: Revert allowing olinks from options
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>
2016-04-14 21:31:02 +02:00
aszlig
41f170f439
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-14 21:24:50 +02:00
Vladimír Čunát
39ebb01d6e Merge branch 'staging', containing closure-size #7701 2016-04-13 09:25:28 +02:00
Eric Sagnes
e6ae05dd8a input-method module: fix folder case 2016-04-12 19:50:26 +09:00
Eric Sagnes
de78fe8f2d manual: add chapter on input methods 2016-04-12 19:50:16 +09:00
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
aszlig
64e566a49c
nixos/taskserver: Add module documentation
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>
2016-04-07 14:26:12 +02:00
Vladimír Čunát
ab15a62c68 Merge branch 'master' into closure-size
Beware that stdenv doesn't build. It seems something more will be needed
than just resolution of merge conflicts.
2016-04-01 10:06:01 +02:00
Pascal Wittmann
8ddfab0cf2 nixos/manpages: enable linebreaking after slashes
Allow linbreaks after slashes in long URLs. The option used
is documented at

   http://docbook.sourceforge.net/release/xsl/current/doc/manpages/man.break.after.slash.html

This commit fixes #4538.
2016-03-19 17:16:59 +01:00
Vladimír Čunát
09af15654f Merge master into closure-size
The kde-5 stuff still didn't merge well.
I hand-fixed what I saw, but there may be more problems.
2016-03-08 09:58:19 +01:00
Eelco Dolstra
f3d94cfc23 Revert "Add the tool "nixos-typecheck" that can check an option declaration to:"
This reverts commit cad8957eab. It
breaks NixOps, but more importantly, such major changes to the module
system really need to be reviewed.
2016-03-01 20:52:06 +01:00
Thomas Strobel
cad8957eab Add the tool "nixos-typecheck" that can check an option declaration to:
- Enforce that an option declaration has a "defaultText" if and only if the
   type of the option derives from "package", "packageSet" or "nixpkgsConfig"
   and if a "default" attribute is defined.

 - Enforce that the value of the "example" attribute is wrapped with "literalExample"
   if the type of the option derives from "package", "packageSet" or "nixpkgsConfig".

 - Warn if a "defaultText" is defined in an option declaration if the type of
   the option does not derive from "package", "packageSet" or "nixpkgsConfig".

 - Warn if no "type" is defined in an option declaration.
2016-02-29 01:09:00 +01:00
Eelco Dolstra
d4636fa254 Revert "Add a way to pin a NixOS version within the module system."
This reverts commit a5992ad61b. Motivation:

a5992ad61b (commitcomment-14986820)
2016-02-27 20:48:12 +01:00
Franz Pletz
cd0f14f23e gitlab: Add documentation
Fixes #13303.
2016-02-26 08:56:39 +01:00
Vladimír Čunát
d039c87984 Merge branch 'master' into closure-size 2016-02-14 08:33:51 +01:00
Vladimír Čunát
ae74c356d9 Merge recent 'staging' into closure-size
Let's get rid of those merge conflicts.
2016-02-03 16:57:19 +01:00
aszlig
6fec28e043
nixos-manual: Further simplify stripAnyPrefixes
First of all this fixes an evaluation error I introduced in ae466ba,
which wasn't triggered by any of my own tests against the change because
there are usually no NixOS options that are declared outside of the
<nixpkgs> tree. I renamed the attribute name from "fn" to "fileName"
first and later to "fullPath" but forgot one still occuring "filename".

Thanks to @vcunat for noticing this.

Another thing that he pointed out was that the "stripPrefix" function
can be factored away entirely, because it's very similar to
"removePrefix" in <nixpkgs/lib>.

Unfortunately we can't use "removePrefix" as is, because we need to
account for the final shlash.

So instead of removing it twice and/or retaining "stripPrefix", let's
append a shlash on every "prefixesToStrip" and we can use "removePrefix"
as is.

Tested with:

taalo-build nixos/release.nix -A tests.installer.simple.x86_64-linux

And:

w3m -dump "$(
  nix-build nixos/release.nix -A manual.x86_64-linux
)/share/doc/nixos/options.html"

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Cc: @vcunat
2016-01-29 20:14:11 +01:00
aszlig
ae466ba15c
nixos-manual: Simplify stripping prefixes
Let's use a simple (unflipped) fold and break out the actual core
stripPrefix function from stripAnyPrefixes (I personally love
point-less^H^H^H^Hfree style but if I'd be anal I'd even go further and
factor away the "fn:").

Also, let's use path as a better name for "fn" (filename), because
that's what it is and also cannot be confused with "fn" meaning
"function".

We now toString all of the prefixes, so there shouldn't be any need to
implicily toString the extraSources anymore.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
2016-01-29 16:33:19 +01:00
aszlig
a581f72f22
nixos-manual: Fix stripping declaration prefixes
Regression introduced by e6cd147ae7.

This broke all of the installer tests, because they needed to rebuild
the manual within the test machine, while it only has a closure of the
already pre-built system in place.

The problem here was just that the order of the arguments got mixed up
in stripAnyPrefixes, so it was actually trying to strip the path off the
prefix, not the other way around.

So in the end no prefix was stripped at all, so we ended up having full
store paths in the manual, which in turn caused the build within the VM
to fail, because the prefixes differed.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
2016-01-29 16:33:19 +01:00
Ryan Artecona
e6cd147ae7 nixos manual: allow options from nix packages 2016-01-22 14:22:12 -05:00
Vladimír Čunát
f9f6f41bff Merge branch 'master' into closure-size
TODO: there was more significant refactoring of qtbase and plasma 5.5
on master, and I'm deferring pointing to correct outputs to later.
2015-12-31 09:53:02 +01:00