From 95dfbe2d632b71a72634d2d65e3f738f500ee5ce Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Sun, 20 Oct 2019 12:17:58 +0200 Subject: doc: organize chapters into parts, and reduce toc depth Reorganize the chapters into parts and reduce the TOC depth to make the TOC useful again. The top-level TOC is very brief, but that is fine because every part will have its own TOC. Section titles of languages/frameworks are also simplified to just the name of the language/framework. --- doc/contributing-to-documentation.xml | 30 ++++++++++++++++++ doc/contributing.xml | 30 ------------------ doc/doc-support/parameters.xml | 2 +- doc/languages-frameworks/emscripten.section.md | 2 +- doc/languages-frameworks/haskell.section.md | 2 +- doc/languages-frameworks/idris.section.md | 2 +- doc/languages-frameworks/index.xml | 2 +- doc/languages-frameworks/node.section.md | 4 +-- doc/languages-frameworks/r.section.md | 4 +-- doc/languages-frameworks/rust.section.md | 2 +- doc/languages-frameworks/vim.section.md | 2 +- doc/manual.xml | 44 ++++++++++++++++---------- doc/platform-notes.xml | 2 +- doc/reviewing-contributions.xml | 2 +- 14 files changed, 71 insertions(+), 59 deletions(-) create mode 100644 doc/contributing-to-documentation.xml delete mode 100644 doc/contributing.xml diff --git a/doc/contributing-to-documentation.xml b/doc/contributing-to-documentation.xml new file mode 100644 index 00000000000..b0266043775 --- /dev/null +++ b/doc/contributing-to-documentation.xml @@ -0,0 +1,30 @@ + + Contributing to this documentation + + The DocBook sources of the Nixpkgs manual are in the doc subdirectory of the Nixpkgs repository. + + + You can quickly check your edits with make: + + +$ cd /path/to/nixpkgs/doc +$ nix-shell +[nix-shell]$ make + + + If you experience problems, run make debug to help understand the docbook errors. + + + After making modifications to the manual, it's important to build it before committing. You can do that as follows: + +$ cd /path/to/nixpkgs/doc +$ nix-shell +[nix-shell]$ make clean +[nix-shell]$ nix-build . + + If the build succeeds, the manual will be in ./result/share/doc/nixpkgs/manual.html. + + diff --git a/doc/contributing.xml b/doc/contributing.xml deleted file mode 100644 index b0266043775..00000000000 --- a/doc/contributing.xml +++ /dev/null @@ -1,30 +0,0 @@ - - Contributing to this documentation - - The DocBook sources of the Nixpkgs manual are in the doc subdirectory of the Nixpkgs repository. - - - You can quickly check your edits with make: - - -$ cd /path/to/nixpkgs/doc -$ nix-shell -[nix-shell]$ make - - - If you experience problems, run make debug to help understand the docbook errors. - - - After making modifications to the manual, it's important to build it before committing. You can do that as follows: - -$ cd /path/to/nixpkgs/doc -$ nix-shell -[nix-shell]$ make clean -[nix-shell]$ nix-build . - - If the build succeeds, the manual will be in ./result/share/doc/nixpkgs/manual.html. - - diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml index bc13e2b70de..e4b33e66ee4 100644 --- a/doc/doc-support/parameters.xml +++ b/doc/doc-support/parameters.xml @@ -8,7 +8,7 @@ - + diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md index 24c49ec1409..80e1094809a 100644 --- a/doc/languages-frameworks/emscripten.section.md +++ b/doc/languages-frameworks/emscripten.section.md @@ -1,4 +1,4 @@ -# User's Guide to Emscripten in Nixpkgs +# Emscripten [Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index 48d22831cd9..1e677450aa1 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -3,7 +3,7 @@ title: User's Guide for Haskell in Nixpkgs author: Peter Simons date: 2015-06-01 --- -# User's Guide to the Haskell Infrastructure +# Haskell ## How to install Haskell packages diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md index e88015f08e3..8d7962d7fb9 100644 --- a/doc/languages-frameworks/idris.section.md +++ b/doc/languages-frameworks/idris.section.md @@ -1,4 +1,4 @@ -# Idris packages +# Idris ## Installing Idris diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index cd0b48adb14..86076085799 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -1,7 +1,7 @@ - Support for specific programming languages and frameworks + Languages and frameworks The standard build environment makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accomodated by overriding the appropriate phases of stdenv. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter. diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md index c6dce04c7b8..4dc95fc1dd9 100644 --- a/doc/languages-frameworks/node.section.md +++ b/doc/languages-frameworks/node.section.md @@ -1,5 +1,5 @@ -Node.js packages -================ +Node.js +======= The `pkgs/development/node-packages` folder contains a generated collection of [NPM packages](https://npmjs.com/) that can be installed with the Nix package manager. diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md index c8f02bd1478..d4e1617779c 100644 --- a/doc/languages-frameworks/r.section.md +++ b/doc/languages-frameworks/r.section.md @@ -1,5 +1,5 @@ -R packages -========== +R += ## Installation diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index 83b7b159bd6..31f1abd197b 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -4,7 +4,7 @@ author: Matthias Beyer date: 2017-03-05 --- -# User's Guide to the Rust Infrastructure +# Rust To install the rust compiler and cargo put diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 537e7b93e52..05a23d26cf2 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -3,7 +3,7 @@ title: User's Guide for Vim in Nixpkgs author: Marc Weber date: 2016-06-25 --- -# User's Guide to Vim Plugins/Addons/Bundles/Scripts in Nixpkgs +# Vim Both Neovim and Vim can be configured to include your favorite plugins and additional libraries. diff --git a/doc/manual.xml b/doc/manual.xml index ab845e1a108..7015e18d1e9 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -6,20 +6,32 @@ - - - - - - - - - - - - - - - - + + Using Nixpkgs + + + + + + Standard environment + + + + + + + + Languages, frameworks and packages + + + + + + Contributing to Nixpkgs + + + + + + diff --git a/doc/platform-notes.xml b/doc/platform-notes.xml index d8d7692fc9a..5a266fdc0ee 100644 --- a/doc/platform-notes.xml +++ b/doc/platform-notes.xml @@ -1,6 +1,6 @@ + xml:id="chap-platform-notes"> Platform Notes
Darwin (macOS) diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml index 5a14684f9b1..c6fb6256781 100644 --- a/doc/reviewing-contributions.xml +++ b/doc/reviewing-contributions.xml @@ -2,7 +2,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" - xml:id="sec-reviewing-contributions"> + xml:id="chap-reviewing-contributions"> Reviewing contributions -- cgit 1.4.1