diff options
author | Graham Christensen <graham@grahamc.com> | 2018-08-27 19:54:41 -0400 |
---|---|---|
committer | Graham Christensen <graham@grahamc.com> | 2018-08-27 19:54:41 -0400 |
commit | 360f420ac7df37e8987473f49e00175ef70732b8 (patch) | |
tree | 19e33a0b869bfec1901d81010d5c6bf22d5dff5a /doc | |
parent | 53371b15c6f287b627e1255bb21d54e123e1f96f (diff) |
nixpkgs docs: normalize
Diffstat (limited to 'doc')
-rw-r--r-- | doc/functions.xml | 31 | ||||
-rw-r--r-- | doc/languages-frameworks/java.xml | 24 | ||||
-rw-r--r-- | doc/package-notes.xml | 48 | ||||
-rw-r--r-- | doc/platform-notes.xml | 8 | ||||
-rw-r--r-- | doc/reviewing-contributions.xml | 39 |
5 files changed, 80 insertions, 70 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 9bbf97c5c71e..ec188e234543 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -523,7 +523,8 @@ merge:"diff3" <callout arearefs='ex-dockerTools-buildImage-2'> <para> <varname>tag</varname> specifies the tag of the resulting image. By - default it's <literal>null</literal>, which indicates that the nix output hash will be used as tag. + default it's <literal>null</literal>, which indicates that the nix output + hash will be used as tag. </para> </callout> <callout arearefs='ex-dockerTools-buildImage-3'> @@ -669,12 +670,12 @@ merge:"diff3" <para> <varname>imageDigest</varname> specifies the digest of the image to be downloaded. Skopeo can be used to get the digest of an image, with its - <varname>inspect</varname> subcommand. Since a given <varname>imageName</varname> - may transparently refer to a manifest list of images which support - multiple architectures and/or operating systems, supply the `--override-os` - and `--override-arch` arguments to specify exactly which image you - want. By default it will match the OS and architecture of the host the - command is run on. + <varname>inspect</varname> subcommand. Since a given + <varname>imageName</varname> may transparently refer to a manifest list + of images which support multiple architectures and/or operating systems, + supply the `--override-os` and `--override-arch` arguments to specify + exactly which image you want. By default it will match the OS and + architecture of the host the command is run on. <programlisting> $ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'" sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b @@ -697,16 +698,16 @@ merge:"diff3" </para> </callout> <callout arearefs='ex-dockerTools-pullImage-5'> - <para> - <varname>os</varname>, if specified, is the operating system of the fetched image. - By default it's <literal>linux</literal>. - </para> + <para> + <varname>os</varname>, if specified, is the operating system of the + fetched image. By default it's <literal>linux</literal>. + </para> </callout> <callout arearefs='ex-dockerTools-pullImage-6'> - <para> - <varname>arch</varname>, if specified, is the cpu architecture of the fetched image. - By default it's <literal>x86_64</literal>. - </para> + <para> + <varname>arch</varname>, if specified, is the cpu architecture of the + fetched image. By default it's <literal>x86_64</literal>. + </para> </callout> </calloutlist> </section> diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml index 1acea6a7547a..667a795a8d3a 100644 --- a/doc/languages-frameworks/java.xml +++ b/doc/languages-frameworks/java.xml @@ -16,18 +16,17 @@ stdenv.mkDerivation { } </programlisting> Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built - where available, or pre-built via Zulu). - Platforms with OpenJDK not (yet) in Nixpkgs (<literal>Aarch32</literal>, - <literal>Aarch64</literal>) point to the (unfree) - <literal>oraclejdk</literal>. -</para> + where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in + Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the + (unfree) <literal>oraclejdk</literal>. + </para> <para> JAR files that are intended to be used by other packages should be installed - in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook - that add any JARs in the <filename>share/java</filename> directories of the - build inputs to the <envar>CLASSPATH</envar> environment variable. For - instance, if the package <literal>libfoo</literal> installs a JAR named + in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that + add any JARs in the <filename>share/java</filename> directories of the build + inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if + the package <literal>libfoo</literal> installs a JAR named <filename>foo.jar</filename> in its <filename>share/java</filename> directory, and another package declares the attribute <programlisting> @@ -61,18 +60,17 @@ installPhase = <literal>${jre}/bin/java</literal> instead of <literal>${jdk}/bin/java</literal>, you prevent your package from depending on the JDK at runtime. -</para> + </para> -<para> + <para> Note all JDKs passthru <literal>home</literal>, so if your application requires environment variables like <envar>JAVA_HOME</envar> being set, that can be done in a generic fashion with the <literal>--set</literal> argument of <literal>makeWrapper</literal>: - <programlisting> --set JAVA_HOME ${jdk.home} </programlisting> -</para> + </para> <para> It is possible to use a different Java compiler than <command>javac</command> diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 0634432fe95a..8c7c63c8c8d7 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -709,40 +709,50 @@ overrides = super: self: rec { <title>Citrix Receiver</title> <para> - The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> is a remote - desktop viewer which provides access to - <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations. + The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix + Receiver</link> is a remote desktop viewer which provides access to + <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> + installations. </para> <section xml:id="sec-citrix-base"> <title>Basic usage</title> + <para> - The tarball archive needs to be downloaded manually as the licenses agreements of the vendor - need to be accepted first. This is available at the - <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download page at citrix.com</link>. - Then run <literal>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</literal>. - With the archive available in the store the package can be built and installed with Nix. + The tarball archive needs to be downloaded manually as the licenses + agreements of the vendor need to be accepted first. This is available at + the + <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download + page at citrix.com</link>. Then run <literal>nix-prefetch-url + file://$PWD/linuxx64-$version.tar.gz</literal>. With the archive available + in the store the package can be built and installed with Nix. </para> <para> - <emphasis>Note: it's recommended to install <literal>Citrix Receiver</literal> using - <literal>nix-env -i</literal> or globally to ensure that the <literal>.desktop</literal> files - are installed properly into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't - be possible to open <literal>.ica</literal> files - automatically from the browser to start a Citrix connection.</emphasis> + <emphasis>Note: it's recommended to install <literal>Citrix + Receiver</literal> using <literal>nix-env -i</literal> or globally to + ensure that the <literal>.desktop</literal> files are installed properly + into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to + open <literal>.ica</literal> files automatically from the browser to start + a Citrix connection.</emphasis> </para> </section> + <section xml:id="sec-citrix-custom-certs"> <title>Custom certificates</title> + <para> - The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts several certificates - <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. - However several companies using Citrix might require their own corporate certificate. On distros with imperative + The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts + several certificates + <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the + Mozilla database</link> by default. However several companies using Citrix + might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, - however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple - mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>: - + however this directory is a store path in <literal>nixpkgs</literal>. In + order to work around this issue the package provides a simple mechanism to + add custom certificates without rebuilding the entire package using + <literal>symlinkJoin</literal>: <programlisting> <![CDATA[with import <nixpkgs> { config.allowUnfree = true; }; let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in diff --git a/doc/platform-notes.xml b/doc/platform-notes.xml index ea581421547d..cde27b8a5edf 100644 --- a/doc/platform-notes.xml +++ b/doc/platform-notes.xml @@ -29,7 +29,6 @@ } </programlisting> </listitem> - <listitem> <para> On darwin libraries are linked using absolute paths, libraries are @@ -47,19 +46,19 @@ } </programlisting> </listitem> - <listitem> <para> Even if the libraries are linked using absolute paths and resolved via their <literal>install_name</literal> correctly, tests can sometimes fail - to run binaries. This happens because the <varname>checkPhase</varname> + to run binaries. This happens because the <varname>checkPhase</varname> runs before the libraries are installed. </para> <para> This can usually be solved by running the tests after the <varname>installPhase</varname> or alternatively by using <varname>DYLD_LIBRARY_PATH</varname>. More information about this variable - can be found in the <citerefentry><refentrytitle>dyld</refentrytitle> + can be found in the <citerefentry> + <refentrytitle>dyld</refentrytitle> <manvolnum>1</manvolnum></citerefentry> manpage. </para> <programlisting> @@ -77,7 +76,6 @@ } </programlisting> </listitem> - <listitem> <para> Some packages assume xcode is available and use <command>xcrun</command> diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml index b2a2675c3e65..6b854e085549 100644 --- a/doc/reviewing-contributions.xml +++ b/doc/reviewing-contributions.xml @@ -6,18 +6,20 @@ <title>Reviewing contributions</title> <warning> <para> - The following section is a draft, and the policy for reviewing is still being - discussed in issues such as <link + The following section is a draft, and the policy for reviewing is still + being discussed in issues such as + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/11166">#11166 - </link> and <link + </link> and + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/20836">#20836 </link>. </para> </warning> <para> - The nixpkgs project receives a fairly high number of contributions via - GitHub pull-requests. Reviewing and approving these is an important task and - a way to contribute to the project. + The nixpkgs project receives a fairly high number of contributions via GitHub + pull-requests. Reviewing and approving these is an important task and a way + to contribute to the project. </para> <para> The high change rate of nixpkgs makes any pull request that remains open for @@ -40,10 +42,10 @@ to respect every community member and their work. </para> <para> - GitHub provides reactions as a simple and quick way to provide - feedback to pull-requests or any comments. The thumb-down reaction should be - used with care and if possible accompanied with some explanation so the - submitter has directions to improve their contribution. + GitHub provides reactions as a simple and quick way to provide feedback to + pull-requests or any comments. The thumb-down reaction should be used with + care and if possible accompanied with some explanation so the submitter has + directions to improve their contribution. </para> <para> Pull-request reviews should include a list of what has been reviewed in a @@ -117,8 +119,8 @@ <itemizedlist> <listitem> <para> - License can change with version updates, so it should be checked to match - the upstream license. + License can change with version updates, so it should be checked to + match the upstream license. </para> </listitem> <listitem> @@ -143,8 +145,8 @@ <listitem> <para> Pull-requests are often targeted to the master or staging branch, and - building the pull-request locally when it is submitted can trigger - many source builds. + building the pull-request locally when it is submitted can trigger many + source builds. </para> <para> It is possible to rebase the changes on nixos-unstable or @@ -605,11 +607,12 @@ policy. --> <para> - In a case a contributor leaves definitively the Nix community, he - should create an issue or post on <link + In a case a contributor leaves definitively the Nix community, he should + create an issue or post on + <link xlink:href="https://discourse.nixos.org">Discourse</link> with - references of packages and modules he maintains so the - maintainership can be taken over by other contributors. + references of packages and modules he maintains so the maintainership can be + taken over by other contributors. </para> </section> </chapter> |