[RFC] manual: rename to users and contributors manual, add some user notes … #60682

7c6f434c · 2019-05-01T22:36:32Z

…that should be there but don't fit in any chapter

Motivation for this change

Answering questions about locales on non-NixOS makes me wonder why it is still not in the Nixpkgs manual.

Things done

Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS)
Built on platform(s)
- NixOS
- macOS
- other Linux distributions
Assured whether relevant documentation is up to date (this is the entirety of the PR)
Fits CONTRIBUTING.md.

worldofpeace · 2019-05-02T00:38:14Z

doc/package-specific-notes.chapter.md

+set of locales. It is possible to build a custom set of locales by overriding
+parameters `allLocales` and `locales` of the package.
+
+## Unfree software


This is going to make a lot of new users, who struggle to figure this out, lives a lot easier 👍

Initially I tried to also explain the reasons for the default state (not even visible to search), but decided that I don't want to give the remarks on unfree software too much prominence…

I think that's a good call. The documentation itself should remain neutral and just serve to inform.

Hmm there's also some stuff about allowUnfree at https://nixos.org/nixpkgs/manual/#chap-packageconfig

I don't think rationale should never be explained (there are technical reasons), but I had various non-neutral goals about appearance of that paragraph (I wanted it to be slightly negative and not too prominent — to reflect the attitudes evident in the relevant discussions)

NixOS manual describes the setting in context of NixOS configuration (and it only affects NixOS evaluation there…), Nixpkgs manual should cover the setting in the context of Nixpkgs configuration for use via other means.

Oh, it wasn't explicitly linked to #17126

worldofpeace · 2019-05-02T19:45:19Z

doc/package-specific-notes.chapter.md

@@ -0,0 +1,52 @@
+---
+title: Package-specific notes


I feel like this is very similar to https://nixos.org/nixpkgs/manual/#chap-package-notes?

See the intro

This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages such as the Linux kernel or X.org.

Any reason why the notes here don't belong there and warrants its own new chapter?

Oops, I haven't read the manual since forever (yo can only trust source code!), so I skimmed the chapter list and missed that.

On the other hand, I think the package notes are a mess right now, as there is no separation between notes of type «this is how you update X.org» and «this is how you use Steam»

I can totally understand that, but the notes do have to go somewhere appropriate in the manual and it would be the best place their is currently. But a restructuring is needed as you said.

Yes, I did miss the preexisting section initially.

Actually, maybe it should be split with package use notes going closer to the beginning and package editing notes staying after all the explanations of package writing?

Actually, maybe it should be split with package use notes going closer to the beginning and package editing notes staying after all the explanations of package writing?

Subsections like that could help, yes.

# Packages Notes: ## Using packages [explanation/intro] ## Writing packages [explanation/intro]

If I'm understanding correctly?

No. «Using packages» should be before the detailed walkthrough os stdenv code; «Updating speciric packages» should obviously be after all the generic explanations…

7c6f434c · 2019-05-10T17:05:24Z

OK, implemented my plan about redistribution between user notes and development notes.

chreekat · 2019-05-16T19:29:24Z

Great idea!

ryantm · 2019-05-21T12:55:26Z

doc/package-specific-user-notes.xml

+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="package-specific-user-notes">
+ <title>Package-specific usage notes</title>
+ <para>
+         This chapters includes some notes


Suggested change

This chapters includes some notes

These chapters includes some notes

ryantm · 2019-05-22T02:15:32Z

doc/package-specific-user-notes.xml

+  <para>
+   All users of Nixpkgs are free software users, and many users (and
+   developers) of Nixpkgs want to limit and tightly control their exposure to
+   unfree software. At the same many users need (or want) to run some specific


Suggested change

unfree software. At the same many users need (or want) to run some specific

unfree software. At the same time, many users need (or want) to run some specific

ryantm · 2019-05-22T02:16:35Z

doc/package-specific-user-notes.xml

+   <para>
+    Steam is distributed as a <filename>.deb</filename> file, for now only as
+    an i686 package (the amd64 package only has documentation). When unpacked,
+    it has a script called <filename>steam</filename> that in ubuntu (their


Suggested change

it has a script called <filename>steam</filename> that in ubuntu (their

it has a script called <filename>steam</filename> that in Ubuntu (their

ryantm · 2019-05-22T02:19:58Z

doc/package-specific-user-notes.xml

+   <title>Basic usage</title>
+
+   <para>
+    The tarball archive needs to be downloaded manually as the licenses


Suggested change

The tarball archive needs to be downloaded manually as the licenses

The tarball archive needs to be downloaded manually as the license

7c6f434c · 2019-05-22T04:54:31Z

Thank you

…that should be there but don't fit in any chapter

…he upper user notes section

7c6f434c changed the title ~~manual: rename to users and contributors manual, add some user notes …~~ [RFC] manual: rename to users and contributors manual, add some user notes … May 1, 2019

ofborg bot added 8.has: documentation 10.rebuild-darwin: 0 10.rebuild-linux: 0 labels May 1, 2019

worldofpeace reviewed May 2, 2019

View reviewed changes

7c6f434c force-pushed the manual-user-notes branch from 5fe55a2 to 6955baf Compare May 10, 2019 17:04

7c6f434c requested a review from grahamc May 16, 2019 12:27

7c6f434c requested review from zimbatm and ryantm May 20, 2019 17:36

ryantm requested changes May 22, 2019

View reviewed changes

7c6f434c force-pushed the manual-user-notes branch from e0d58d7 to 207edba Compare May 22, 2019 04:49

7c6f434c added 6 commits May 22, 2019 06:56

manual: rename to users and contributors manual, add some user notes …

8247216

…that should be there but don't fit in any chapter

package-specific-notes: convert from Markdown to Docbook

bfa2afb

manual: package-specific-user-notes: stress the user targeting

e4d5857

manual: move the package notes that are completely usage-related to t…

6470bcc

…he upper user notes section

manual: link to package-specific development notes from user notes

11c2cf9

Typo fixes

207edba

ryantm approved these changes May 22, 2019

View reviewed changes

7c6f434c merged commit 4e750fa into NixOS:master May 22, 2019

7c6f434c mentioned this pull request Jan 12, 2020

[RFC] Nixpkgs manual structure: visibility of package usage notes #77555

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] manual: rename to users and contributors manual, add some user notes … #60682

[RFC] manual: rename to users and contributors manual, add some user notes … #60682

7c6f434c commented May 1, 2019

worldofpeace May 2, 2019

7c6f434c May 2, 2019

worldofpeace May 2, 2019

worldofpeace May 2, 2019

7c6f434c May 2, 2019

7c6f434c May 12, 2019

worldofpeace May 2, 2019 •

edited

7c6f434c May 2, 2019

7c6f434c May 2, 2019

worldofpeace May 2, 2019

7c6f434c May 2, 2019

worldofpeace May 2, 2019

7c6f434c May 2, 2019

7c6f434c commented May 10, 2019

chreekat commented May 16, 2019

ryantm May 21, 2019

ryantm May 22, 2019

ryantm May 22, 2019

ryantm May 22, 2019

7c6f434c commented May 22, 2019

	This chapters includes some notes
	These chapters includes some notes

	unfree software. At the same many users need (or want) to run some specific
	unfree software. At the same time, many users need (or want) to run some specific

	it has a script called <filename>steam</filename> that in ubuntu (their
	it has a script called <filename>steam</filename> that in Ubuntu (their

	The tarball archive needs to be downloaded manually as the licenses
	The tarball archive needs to be downloaded manually as the license

[RFC] manual: rename to users and contributors manual, add some user notes … #60682

[RFC] manual: rename to users and contributors manual, add some user notes … #60682

Conversation

7c6f434c commented May 1, 2019

Motivation for this change

Things done

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

worldofpeace May 2, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

7c6f434c commented May 10, 2019

chreekat commented May 16, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

7c6f434c commented May 22, 2019

worldofpeace May 2, 2019 •

edited