From 64e566a49c672c289a2680c477843f4eaeb77d96 Mon Sep 17 00:00:00 2001 From: aszlig Date: Thu, 7 Apr 2016 14:11:49 +0200 Subject: 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 --- nixos/doc/manual/configuration/configuration.xml | 1 + nixos/doc/manual/default.nix | 1 + 2 files changed, 2 insertions(+) (limited to 'nixos/doc') diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index caba8fb1f4ad..501ad10788c5 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -28,6 +28,7 @@ effect after you run nixos-rebuild. + diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 746ddc071b6a..130b016aa266 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -58,6 +58,7 @@ let cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml cp ${../../modules/services/misc/gitlab.xml} configuration/gitlab.xml cp ${../../modules/security/acme.xml} configuration/acme.xml + cp ${../../modules/services/misc/taskserver/doc.xml} configuration/taskserver.xml ln -s ${optionsDocBook} options-db.xml echo "${version}" > version ''; -- cgit 1.4.1 From 1d77dcaed37ab47bfe2d90711c01b475a514ff25 Mon Sep 17 00:00:00 2001 From: aszlig Date: Mon, 11 Apr 2016 18:29:00 +0200 Subject: nixos/doc: Allow refs from options to the manual My first attempt to do this was to just use a conditional 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 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 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 Cc: @edolstra --- nixos/doc/manual/default.nix | 75 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 13 deletions(-) (limited to 'nixos/doc') diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 130b016aa266..6261f83ac8b2 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -73,6 +73,63 @@ let ''; + manualXsltprocOptions = toString [ + "--param section.autolabel 1" + "--param section.label.includes.component.label 1" + "--stringparam html.stylesheet style.css" + "--param xref.with.number.and.title 1" + "--param toc.section.depth 3" + "--stringparam admon.style ''" + "--stringparam callout.graphics.extension .gif" + "--stringparam current.docid manual" + "--param chunk.section.depth 0" + "--param chunk.first.sections 1" + "--param use.id.as.filename 1" + "--stringparam generate.toc 'book toc appendix toc'" + "--stringparam chunk.toc ${toc}" + ]; + + olinkDB = stdenv.mkDerivation { + name = "manual-olinkdb"; + + inherit sources; + + buildInputs = [ libxml2 libxslt ]; + + buildCommand = '' + ${copySources} + + xsltproc \ + ${manualXsltprocOptions} \ + --stringparam collect.xref.targets only \ + --stringparam targets.filename "$out/manual.db" \ + --nonet --xinclude \ + ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl \ + ./manual.xml + + # Check the validity of the man pages sources. + xmllint --noout --nonet --xinclude --noxincludenode \ + --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ + ./man-pages.xml + + cat > "$out/olinkdb.xml" < + + ]> + + + Allows for cross-referencing olinks between the manpages + and the HTML/PDF manuals. + + + &manualtargets; + + EOF + ''; + }; + in rec { # The NixOS options in JSON format. @@ -115,18 +172,8 @@ in rec { dst=$out/share/doc/nixos mkdir -p $dst xsltproc \ - --param section.autolabel 1 \ - --param section.label.includes.component.label 1 \ - --stringparam html.stylesheet style.css \ - --param xref.with.number.and.title 1 \ - --param toc.section.depth 3 \ - --stringparam admon.style "" \ - --stringparam callout.graphics.extension .gif \ - --param chunk.section.depth 0 \ - --param chunk.first.sections 1 \ - --param use.id.as.filename 1 \ - --stringparam generate.toc "book toc appendix toc" \ - --stringparam chunk.toc ${toc} \ + ${manualXsltprocOptions} \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ --nonet --xinclude --output $dst/ \ ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl ./manual.xml @@ -158,6 +205,7 @@ in rec { dst=$out/share/doc/nixos mkdir -p $dst xmllint --xinclude manual.xml | dblatex -o $dst/manual.pdf - \ + -P target.database.document="${olinkDB}/olinkdb.xml" \ -P doc.collab.show=0 \ -P latex.output.revhistory=0 @@ -177,7 +225,7 @@ in rec { buildCommand = '' ${copySources} - # Check the validity of the manual sources. + # Check the validity of the man pages sources. xmllint --noout --nonet --xinclude --noxincludenode \ --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ ./man-pages.xml @@ -189,6 +237,7 @@ in rec { --param man.output.base.dir "'$out/share/man/'" \ --param man.endnotes.are.numbered 0 \ --param man.break.after.slash 1 \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ ${docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \ ./man-pages.xml ''; -- cgit 1.4.1 From c36d6e59647794aa1c4dbb2dcd7e5242d9c5b6b8 Mon Sep 17 00:00:00 2001 From: aszlig Date: Thu, 14 Apr 2016 21:31:02 +0200 Subject: nixos/doc: Revert allowing olinks from options This reverts commit 1d77dcaed37ab47bfe2d90711c01b475a514ff25. 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 --- nixos/doc/manual/default.nix | 75 ++++++++------------------------------------ 1 file changed, 13 insertions(+), 62 deletions(-) (limited to 'nixos/doc') diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 6261f83ac8b2..130b016aa266 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -73,63 +73,6 @@ let ''; - manualXsltprocOptions = toString [ - "--param section.autolabel 1" - "--param section.label.includes.component.label 1" - "--stringparam html.stylesheet style.css" - "--param xref.with.number.and.title 1" - "--param toc.section.depth 3" - "--stringparam admon.style ''" - "--stringparam callout.graphics.extension .gif" - "--stringparam current.docid manual" - "--param chunk.section.depth 0" - "--param chunk.first.sections 1" - "--param use.id.as.filename 1" - "--stringparam generate.toc 'book toc appendix toc'" - "--stringparam chunk.toc ${toc}" - ]; - - olinkDB = stdenv.mkDerivation { - name = "manual-olinkdb"; - - inherit sources; - - buildInputs = [ libxml2 libxslt ]; - - buildCommand = '' - ${copySources} - - xsltproc \ - ${manualXsltprocOptions} \ - --stringparam collect.xref.targets only \ - --stringparam targets.filename "$out/manual.db" \ - --nonet --xinclude \ - ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl \ - ./manual.xml - - # Check the validity of the man pages sources. - xmllint --noout --nonet --xinclude --noxincludenode \ - --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ - ./man-pages.xml - - cat > "$out/olinkdb.xml" < - - ]> - - - Allows for cross-referencing olinks between the manpages - and the HTML/PDF manuals. - - - &manualtargets; - - EOF - ''; - }; - in rec { # The NixOS options in JSON format. @@ -172,8 +115,18 @@ in rec { dst=$out/share/doc/nixos mkdir -p $dst xsltproc \ - ${manualXsltprocOptions} \ - --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ + --param section.autolabel 1 \ + --param section.label.includes.component.label 1 \ + --stringparam html.stylesheet style.css \ + --param xref.with.number.and.title 1 \ + --param toc.section.depth 3 \ + --stringparam admon.style "" \ + --stringparam callout.graphics.extension .gif \ + --param chunk.section.depth 0 \ + --param chunk.first.sections 1 \ + --param use.id.as.filename 1 \ + --stringparam generate.toc "book toc appendix toc" \ + --stringparam chunk.toc ${toc} \ --nonet --xinclude --output $dst/ \ ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl ./manual.xml @@ -205,7 +158,6 @@ in rec { dst=$out/share/doc/nixos mkdir -p $dst xmllint --xinclude manual.xml | dblatex -o $dst/manual.pdf - \ - -P target.database.document="${olinkDB}/olinkdb.xml" \ -P doc.collab.show=0 \ -P latex.output.revhistory=0 @@ -225,7 +177,7 @@ in rec { buildCommand = '' ${copySources} - # Check the validity of the man pages sources. + # Check the validity of the manual sources. xmllint --noout --nonet --xinclude --noxincludenode \ --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ ./man-pages.xml @@ -237,7 +189,6 @@ in rec { --param man.output.base.dir "'$out/share/man/'" \ --param man.endnotes.are.numbered 0 \ --param man.break.after.slash 1 \ - --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ ${docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \ ./man-pages.xml ''; -- cgit 1.4.1