diff options
author | Robert Helgesson <robert@rycee.net> | 2018-05-11 19:25:06 +0200 |
---|---|---|
committer | Robert Helgesson <robert@rycee.net> | 2018-05-11 22:26:21 +0200 |
commit | ec3cbf81c43805468a60d953ebe63b7c9d07ef11 (patch) | |
tree | 1f27ebe4d3d07c69e83ceaa28199d9a9f8d1171d | |
parent | 1a471b0a45ac15f1128f2f948b50da2677728164 (diff) |
manual: some cleanups
-rw-r--r-- | doc/default.nix | 30 | ||||
-rw-r--r-- | doc/manual.xml | 19 | ||||
-rw-r--r-- | doc/options-to-docbook.xsl | 239 | ||||
-rw-r--r-- | doc/overrides.css | 9 | ||||
-rw-r--r-- | doc/style.css | 271 | ||||
-rw-r--r-- | modules/manual.nix | 2 |
6 files changed, 539 insertions, 31 deletions
diff --git a/doc/default.nix b/doc/default.nix index 8b995c5a688..f55163d8aa3 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -59,7 +59,7 @@ let # # E.g. if some `options` came from modules in ${pkgs.customModules}/nix, # you'd need to include `extraSources = [ pkgs.customModules ]` - prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); + prefixesToStrip = map (p: "${toString p}/") ([ ./.. ] ++ extraSources); stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip; # Custom "less" that pushes up all the things ending in ".enable*" @@ -78,19 +78,17 @@ let # Convert the list of options into an XML file. optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList); - optionsDocBook = runCommand "options-db.xml" {} '' - optionsXML=${optionsXML} - if grep /home--manager/modules $optionsXML; then - echo "The manual appears to depend on the location of Home Manager, which is bad" - echo "since this prevents sharing via the NixOS channel. This is typically" - echo "caused by an option default that refers to a relative path (see above" - echo "for hints about the offending path)." - exit 1 - fi - ${buildPackages.libxslt.bin}/bin/xsltproc \ - --stringparam revision '${revision}' \ - -o $out ${<nixpkgs/nixos/doc/manual/options-to-docbook.xsl>} $optionsXML - ''; + optionsDocBook = runCommand "options-db.xml" + { + nativeBuildInputs = [ buildPackages.libxslt.bin ]; + } + '' + optionsXML=${optionsXML} + xsltproc \ + --stringparam program 'home-manager' \ + --stringparam revision '${revision}' \ + -o $out ${./options-to-docbook.xsl} $optionsXML + ''; sources = lib.sourceFilesBySuffices ./. [".xml"]; @@ -268,8 +266,8 @@ in rec { mkdir -p $dst/images/callouts cp ${docbook5_xsl}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/ - cp ${../../../doc/style.css} $dst/style.css - cp ${../../../doc/overrides.css} $dst/overrides.css + cp ${./style.css} $dst/style.css + cp ${./overrides.css} $dst/overrides.css cp -r ${pkgs.documentation-highlighter} $dst/highlightjs mkdir -p $out/nix-support diff --git a/doc/manual.xml b/doc/manual.xml index 9998763606e..f076f833886 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -2,27 +2,19 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" - xml:id="book-nixos-manual"> + xml:id="book-home-manager-manual"> <info> <title>Home Manager Manual</title> </info> <preface> <title>Preface</title> <para> - This manual will eventually describes how to install, use and + This manual will eventually describes how to install, use, and extend Home Manager. </para> <para> - If you encounter problems, please report them on the - <literal - xlink:href="https://groups.google.com/forum/#!forum/nix-devel">nix-devel</literal> - mailing list or on the <link - xlink:href="irc://irc.freenode.net/#nixos"> - <literal>#nixos</literal> channel on Freenode</link>. Bugs should be - reported in - <link - xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’ - GitHub issue tracker</link>. + If you encounter problems or bugs then please report them on the + <link xlink:href="https://github.com/rycee/home-manager/issues">Home Manager issue tracker</link>. </para> <note> <para> @@ -34,7 +26,6 @@ </preface> <appendix xml:id="ch-options"> <title>Configuration Options</title> - <xi:include href="./generated/options-db.xml" - xpointer="configuration-variable-list" /> + <xi:include href="./generated/options-db.xml" xpointer="configuration-variable-list" /> </appendix> </book> diff --git a/doc/options-to-docbook.xsl b/doc/options-to-docbook.xsl new file mode 100644 index 00000000000..0fef4e1df65 --- /dev/null +++ b/doc/options-to-docbook.xsl @@ -0,0 +1,239 @@ +<?xml version="1.0"?> + +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://exslt.org/strings" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns="http://docbook.org/ns/docbook" + extension-element-prefixes="str" + > + + <xsl:output method='xml' encoding="UTF-8" /> + + <xsl:param name="revision" /> + <xsl:param name="program" /> + + + <xsl:template match="/expr/list"> + <appendix> + <title>Configuration Options</title> + <variablelist xml:id="configuration-variable-list"> + <xsl:for-each select="attrs"> + <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '<', '_'), '>', '_'), '?', '_'))" /> + <varlistentry> + <term xlink:href="#{$id}"> + <xsl:attribute name="xml:id"><xsl:value-of select="$id"/></xsl:attribute> + <option> + <xsl:value-of select="attr[@name = 'name']/string/@value" /> + </option> + </term> + + <listitem> + + <para> + <xsl:value-of disable-output-escaping="yes" + select="attr[@name = 'description']/string/@value" /> + </para> + + <xsl:if test="attr[@name = 'type']"> + <para> + <emphasis>Type:</emphasis> + <xsl:text> </xsl:text> + <xsl:value-of select="attr[@name = 'type']/string/@value"/> + <xsl:if test="attr[@name = 'readOnly']/bool/@value = 'true'"> + <xsl:text> </xsl:text> + <emphasis>(read only)</emphasis> + </xsl:if> + </para> + </xsl:if> + + <xsl:if test="attr[@name = 'default']"> + <para> + <emphasis>Default:</emphasis> + <xsl:text> </xsl:text> + <xsl:apply-templates select="attr[@name = 'default']" mode="top" /> + </para> + </xsl:if> + + <xsl:if test="attr[@name = 'example']"> + <para> + <emphasis>Example:</emphasis> + <xsl:text> </xsl:text> + <xsl:choose> + <xsl:when test="attr[@name = 'example']/attrs[attr[@name = '_type' and string[@value = 'literalExample']]]"> + <programlisting><xsl:value-of select="attr[@name = 'example']/attrs/attr[@name = 'text']/string/@value" /></programlisting> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates select="attr[@name = 'example']" mode="top" /> + </xsl:otherwise> + </xsl:choose> + </para> + </xsl:if> + + <xsl:if test="attr[@name = 'relatedPackages']"> + <para> + <emphasis>Related packages:</emphasis> + <xsl:text> </xsl:text> + <xsl:value-of disable-output-escaping="yes" + select="attr[@name = 'relatedPackages']/string/@value" /> + </para> + </xsl:if> + + <xsl:if test="count(attr[@name = 'declarations']/list/*) != 0"> + <para> + <emphasis>Declared by:</emphasis> + </para> + <xsl:apply-templates select="attr[@name = 'declarations']" /> + </xsl:if> + + <xsl:if test="count(attr[@name = 'definitions']/list/*) != 0"> + <para> + <emphasis>Defined by:</emphasis> + </para> + <xsl:apply-templates select="attr[@name = 'definitions']" /> + </xsl:if> + + </listitem> + + </varlistentry> + + </xsl:for-each> + + </variablelist> + </appendix> + </xsl:template> + + + <xsl:template match="*" mode="top"> + <xsl:choose> + <xsl:when test="string[contains(@value, '
')]"> +<programlisting> +<xsl:text>'' +</xsl:text><xsl:value-of select='str:replace(string/@value, "${", "''${")' /><xsl:text>''</xsl:text></programlisting> + </xsl:when> + <xsl:otherwise> + <literal><xsl:apply-templates /></literal> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + + <xsl:template match="null"> + <xsl:text>null</xsl:text> + </xsl:template> + + + <xsl:template match="string"> + <xsl:choose> + <xsl:when test="(contains(@value, '"') or contains(@value, '\')) and not(contains(@value, '
'))"> + <xsl:text>''</xsl:text><xsl:value-of select='str:replace(@value, "${", "''${")' /><xsl:text>''</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>"</xsl:text><xsl:value-of select="str:replace(str:replace(str:replace(str:replace(@value, '\', '\\'), '"', '\"'), '
', '\n'), '$', '\$')" /><xsl:text>"</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + + <xsl:template match="int"> + <xsl:value-of select="@value" /> + </xsl:template> + + + <xsl:template match="bool[@value = 'true']"> + <xsl:text>true</xsl:text> + </xsl:template> + + + <xsl:template match="bool[@value = 'false']"> + <xsl:text>false</xsl:text> + </xsl:template> + + + <xsl:template match="list"> + [ + <xsl:for-each select="*"> + <xsl:apply-templates select="." /> + <xsl:text> </xsl:text> + </xsl:for-each> + ] + </xsl:template> + + + <xsl:template match="attrs[attr[@name = '_type' and string[@value = 'literalExample']]]"> + <xsl:value-of select="attr[@name = 'text']/string/@value" /> + </xsl:template> + + + <xsl:template match="attrs"> + { + <xsl:for-each select="attr"> + <xsl:value-of select="@name" /> + <xsl:text> = </xsl:text> + <xsl:apply-templates select="*" /><xsl:text>; </xsl:text> + </xsl:for-each> + } + </xsl:template> + + + <xsl:template match="derivation"> + <replaceable>(build of <xsl:value-of select="attr[@name = 'name']/string/@value" />)</replaceable> + </xsl:template> + + <xsl:template match="attr[@name = 'declarations' or @name = 'definitions']"> + <simplelist> + <xsl:for-each select="list/string"> + <member><filename> + <!-- Hyperlink the filename either to the NixOS Subversion + repository (if it’s a module and we have a revision number), + or to the local filesystem. --> + <xsl:choose> + <xsl:when test="not(starts-with(@value, '/'))"> + <xsl:choose> + <xsl:when test="$program = 'home-manager'"> + <xsl:attribute name="xlink:href">https://github.com/rycee/home-manager/blob/<xsl:value-of select="$revision"/>/<xsl:value-of select="@value"/>#blob-path</xsl:attribute> + </xsl:when> + <xsl:when test="$revision = 'local'"> + <xsl:attribute name="xlink:href">https://github.com/NixOS/nixpkgs/blob/master/<xsl:value-of select="@value"/></xsl:attribute> + </xsl:when> + <xsl:otherwise> + <xsl:attribute name="xlink:href">https://github.com/NixOS/nixpkgs/blob/<xsl:value-of select="$revision"/>/<xsl:value-of select="@value"/></xsl:attribute> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:when test="$revision != 'local' and $program = 'nixops' and contains(@value, '/nix/')"> + <xsl:attribute name="xlink:href">https://github.com/NixOS/nixops/blob/<xsl:value-of select="$revision"/>/nix/<xsl:value-of select="substring-after(@value, '/nix/')"/></xsl:attribute> + </xsl:when> + <xsl:otherwise> + <xsl:attribute name="xlink:href">file://<xsl:value-of select="@value"/></xsl:attribute> + </xsl:otherwise> + </xsl:choose> + <!-- Print the filename and make it user-friendly by replacing the + /nix/store/<hash> prefix by the default location of nixos + sources. --> + <xsl:choose> + <xsl:when test="$program = 'home-manager'"> + <home-manager/<xsl:value-of select="@value"/>> + </xsl:when> + <xsl:when test="not(starts-with(@value, '/'))"> + <nixpkgs/<xsl:value-of select="@value"/>> + </xsl:when> + <xsl:when test="contains(@value, 'nixops') and contains(@value, '/nix/')"> + <nixops/<xsl:value-of select="substring-after(@value, '/nix/')"/>> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="@value" /> + </xsl:otherwise> + </xsl:choose> + </filename></member> + </xsl:for-each> + </simplelist> + </xsl:template> + + + <xsl:template match="function"> + <xsl:text>λ</xsl:text> + </xsl:template> + + +</xsl:stylesheet> diff --git a/doc/overrides.css b/doc/overrides.css new file mode 100644 index 00000000000..4c7d4a31be2 --- /dev/null +++ b/doc/overrides.css @@ -0,0 +1,9 @@ +.docbook .xref img[src^=images\/callouts\/], +.screen img, +.programlisting img { + width: 1em; +} + +.calloutlist img { + width: 1.5em; +} diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 00000000000..0db907815b6 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,271 @@ +/* Copied from http://bakefile.sourceforge.net/, which appears + licensed under the GNU GPL. */ + + +/*************************************************************************** + Basic headers and text: + ***************************************************************************/ + +body +{ + font-family: "Nimbus Sans L", sans-serif; + background: white; + margin: 2em 1em 2em 1em; +} + +h1, h2, h3, h4 +{ + color: #005aa0; +} + +h1 /* title */ +{ + font-size: 200%; +} + +h2 /* chapters, appendices, subtitle */ +{ + font-size: 180%; +} + +/* Extra space between chapters, appendices. */ +div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 +{ + margin-top: 1.5em; +} + +div.section > div.titlepage h2 /* sections */ +{ + font-size: 150%; + margin-top: 1.5em; +} + +h3 /* subsections */ +{ + font-size: 125%; +} + +div.simplesect h2 +{ + font-size: 110%; +} + +div.appendix h3 +{ + font-size: 150%; + margin-top: 1.5em; +} + +div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ +{ + margin-top: 1.4em; + font-size: 125%; +} + +div.refsection h3 +{ + font-size: 110%; +} + + +/*************************************************************************** + Examples: + ***************************************************************************/ + +div.example +{ + border: 1px solid #b0b0b0; + padding: 6px 6px; + margin-left: 1.5em; + margin-right: 1.5em; + background: #f4f4f8; + border-radius: 0.4em; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +div.example p.title +{ + margin-top: 0em; +} + +div.example pre +{ + box-shadow: none; +} + + +/*************************************************************************** + Screen dumps: + ***************************************************************************/ + +pre.screen, pre.programlisting +{ + border: 1px solid #b0b0b0; + padding: 3px 3px; + margin-left: 1.5em; + margin-right: 1.5em; + + background: #f4f4f8; + font-family: monospace; + border-radius: 0.4em; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +div.example pre.programlisting +{ + border: 0px; + padding: 0 0; + margin: 0 0 0 0; +} + +/*************************************************************************** + Notes, warnings etc: + ***************************************************************************/ + +.note, .warning +{ + border: 1px solid #b0b0b0; + padding: 3px 3px; + margin-left: 1.5em; + margin-right: 1.5em; + margin-bottom: 1em; + padding: 0.3em 0.3em 0.3em 0.3em; + background: #fffff5; + border-radius: 0.4em; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +div.note, div.warning +{ + font-style: italic; +} + +div.note h3, div.warning h3 +{ + color: red; + font-size: 100%; + padding-right: 0.5em; + display: inline; +} + +div.note p, div.warning p +{ + margin-bottom: 0em; +} + +div.note h3 + p, div.warning h3 + p +{ + display: inline; +} + +div.note h3 +{ + color: blue; + font-size: 100%; +} + +div.navfooter * +{ + font-size: 90%; +} + + +/*************************************************************************** + Links colors and highlighting: + ***************************************************************************/ + +a { text-decoration: none; } +a:hover { text-decoration: underline; } +a:link { color: #0048b3; } +a:visited { color: #002a6a; } + + +/*************************************************************************** + Table of contents: + ***************************************************************************/ + +div.toc +{ + font-size: 90%; +} + +div.toc dl +{ + margin-top: 0em; + margin-bottom: 0em; +} + + +/*************************************************************************** + Special elements: + ***************************************************************************/ + +tt, code +{ + color: #400000; +} + +.term +{ + font-weight: bold; + +} + +div.variablelist dd p, div.glosslist dd p +{ + margin-top: 0em; +} + +div.variablelist dd, div.glosslist dd +{ + margin-left: 1.5em; +} + +div.glosslist dt +{ + font-style: italic; +} + +.varname +{ + color: #400000; +} + +span.command strong +{ + font-weight: normal; + color: #400000; +} + +div.calloutlist table +{ + box-shadow: none; +} + +table +{ + border-collapse: collapse; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +table.simplelist +{ + text-align: left; + color: #005aa0; + border: 0; + padding: 5px; + background: #fffff5; + font-weight: normal; + font-style: italic; + box-shadow: none; + margin-bottom: 1em; +} + +div.navheader table, div.navfooter table { + box-shadow: none; +} + +div.affiliation +{ + font-style: italic; +} diff --git a/modules/manual.nix b/modules/manual.nix index ae0ff1d9592..b603dac8a19 100644 --- a/modules/manual.nix +++ b/modules/manual.nix @@ -12,7 +12,7 @@ let homeManagerManual = import ../doc { inherit pkgs config; version = "0.1"; - revision = "release-0.1"; + revision = "master"; options = let scrubbedEval = evalModules { |