Port Nix Pills in to a document produced by Nixpkgs

[grahamc]

Issue description

@lethalman gave me permission to incorporate the nix pills in to a document produced by nixpkgs and on the website.

This should probably be its own document.

People who have offered to help write docbook after I make a skeleton to work from:

• @disassembler (disasm on irc)
• @ankhers
• @moretea

(thank you by the way)

Todo:

• http://lethalman.blogspot.it/2014/07/nix-pill-1-why-you-should-give-it-try.html
• http://lethalman.blogspot.it/2014/07/nix-pill-2-install-on-your-running.html
• http://lethalman.blogspot.it/2014/07/nix-pill-3-enter-environment.html
• http://lethalman.blogspot.it/2014/07/nix-pill-4-basics-of-language.html
• http://lethalman.blogspot.it/2014/07/nix-pill-5-functions-and-imports.html
• http://lethalman.blogspot.it/2014/07/nix-pill-6-our-first-derivation.html
• http://lethalman.blogspot.it/2014/07/nix-pill-7-working-derivation.html
• http://lethalman.blogspot.it/2014/08/nix-pill-8-generic-builders.html
• http://lethalman.blogspot.it/2014/08/nix-pill-9-automatic-runtime.html
• http://lethalman.blogspot.it/2014/08/nix-pill-10-developing-with-nix-shell.html
• http://lethalman.blogspot.it/2014/08/nix-pill-11-garbage-collector.html
• http://lethalman.blogspot.it/2014/08/nix-pill-12-inputs-design-pattern.html
• http://lethalman.blogspot.it/2014/09/nix-pill-13-callpackage-design-pattern.html
• http://lethalman.blogspot.it/2014/09/nix-pill-14-override-design-pattern.html
• http://lethalman.blogspot.it/2014/09/nix-pill-15-nix-search-paths.html
• http://lethalman.blogspot.it/2014/11/nix-pill-16-nixpkgs-parameters.html
• http://lethalman.blogspot.it/2014/11/nix-pill-17-nixpkgs-overriding-packages.html
• http://lethalman.blogspot.it/2015/01/nix-pill-18-nix-store-paths.html
• http://lethalman.blogspot.it/2015/08/nix-pill-19-fundamentals-of-stdenv.html

[ixxie]

Is there a standard format for this sort of thing? Where exactly would it go?

[nixy]

@ixxie I am pretty sure this issue is about making a format for all this. From what Graham said there, it looks like this won't be going in any of the manuals and will be it's own thing.

As for where it should go, I think having either a 'Getting Started' or 'Tutorials' section on nixos.org/nix would be fine. Stuff has to be made before we can worry about where to put it though.

[ixxie]

@nixy - I see, I thought it was specifically about Nix Pills. I have been craving a tutorials / cookbook section which is more comprehensive. Perhaps @mbbx6spp and @domenkozar can contribute material from their cookbooks too.

[ixxie]

Regarding format, since the manuals are hierarchical and linear, perhaps a cool thing would be to have CMS style searchable collection of tagged recipes / tutorials ? Then if I searched for, say, "installing unstable packages in stable", I would get all the relevant entries in full and could scroll through them until I find what I need.

[grahamc]

I've started a conversion here: https://github.com/grahamc/nix-pills This project should not get bogged down in a discussion on how NixOS does documentation. This is going to be maintained as a separate document, and linked on the website as something like "read the nix pills."

---

• List of Elements: http://tdg.docbook.org/tdg/5.2/chunk-part-d6252e15351.html
• Tracking Issue: Port Nix Pills in to a document produced by Nixpkgs  #27908

INSTRUCTIONS

When starting a new Pill, comment on this issue which one
you're doing. If you need help, ask there. If you make progress but
don't finish in one go, make a PR anyway! I'm trying to not edit
things as I go, in order to not get bogged down.

Pills are in https://github.com/grahamc/nix-pills/tree/master/pills I already did 1 and 2 to provide examples on how to "docbookify" most of it :)

cc @disassembler @ankhers @moretea

How I've built and tested:

nix-build && firefox result/share/doc/nix-pills/index.html

Emacs config for a nice docbook experience, if you happen to use emacs:

let
 pkgs = import <nixpkgs> {};
 inherit (pkgs) emacsPackagesNg docbook5 writeText;

 schemas = writeText "schemas.xml" ''
   <locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
     <documentElement localName="section" typeId="DocBook"/>
     <documentElement localName="chapter" typeId="DocBook"/>
     <documentElement localName="article" typeId="DocBook"/>
     <documentElement localName="book" typeId="DocBook"/>
     <typeId id="DocBook" uri="${docbook5}/xml/rng/docbook/docbookxi.rnc" />
   </locatingRules>
 '';

in emacsPackagesNg.emacsWithPackages (epkgs: [
 (emacsPackagesNg.trivialBuild {
   pname = "nix-docbook-mode";
   version = "1970-01-01";
   src = writeText "default.el" ''
     (eval-after-load 'rng-loc
       '(add-to-list 'rng-schema-locating-files "${schemas}"))
     (global-set-key (kbd "<C-return>") 'nxml-complete)
   '';
 })
])

Then you can use the keys:

• C-c C-b to finish & close a tag
• C-c C-f to close a tag
• C-return to auto-complete a tag or attribute.

[ankhers]

Thanks for starting this! I will grab pills 3 and 4 to start.

[NeQuissimus]

Oooh, nice! Thank you @lethalman !

[ixxie]

I'll grab 5 and 6 for now :)

[lheckemann]

I'll take 7.

[ixxie]

Alright so some notes now that I ported the fifth pill:

1. Some variables were quoted ("a"); I removed quotes and added literals to make style consistent.
2. I followed @grahamc by using literals for code but I did noticed there are <code> tags; maybe the literals should be replaced at some point.
3. Some paragraphs were ambiguous in that there was a line break in the middle without a gap line. In those cases I removed the break since they seemed like one paragraph rather than two.
4. The link to the functions section in the manual was broken; I had to guess the section intended in the post.
5. The first section missed a title so I added one.

I'll try and do the next one this week.

[grahamc]

I did start by using <literal> for a lot of things, but have since also started to use <code>, <parameter>, and <filename>. For ambiguous paragraphs, I've always broken them in to their own paragraph. I'm not sure there is a right answer here.

Re #5's first section missing a title, that can just be a <para> after the title before the first <section>.

Great work, everyone! We're really blazing through this list!

[lheckemann]

What about <code> vs <programlisting>?

[grahamc]

Yep, a good point to cover. <code> is only appropriate for code fragments, like x: x * 2. For longer blocks of code, programlisting is more appropriate.

That said: we've got a big job ahead of us, and a lot of new tags in docbook that we could discover throughout. I'm not too worried about getting the semantics perfect on the first pass.

[grahamc]

Another one I was just reminded of is <command>.

[lheckemann]

There's also lots to mark up on screen listings: e.g. https://github.com/lheckemann/nix-pills/blob/5f5e3093c478a8bb744ec7ae2c02b77a774b7ec4/pills/07-working-derivation.xml#L61-L65

[grahamc]

Oh jeeze, while all that is probably best, I don't think it is a requirement for merging a PR which is otherwise porting a pill. We can always go back and improve them :P

[ixxie]

@grahamc so instead of <screen>s importing external files one can use <programlisting>s to put multiline code blocks in the file? It would certainly make it easier for future editing.

[lheckemann]

It depends on what you're actually putting in. You should use <screen> if you're putting what a user might see on the screen and <programlisting> if it's code.

[grahamc]

FWIW I put the screen contents in separate files because of difficulties with whitespace in screens.

[lheckemann]

I didn't realise that was possible (and really should have, probably). Good idea!

[ankhers]

I can grab 8 and 9.

[ankhers]

10 and 11

[grahamc]

Hey everyone,

I've been hit by a bad flare-up of my RSI and haven't been able to contribute or review much. I will be back to this soon, but must take a few more days rest to recover. Your work has been incredible and inspiring, thank you so much for making this so fast.

Graham

[ixxie]

Get well @grahamc! Remember to squeeze a rubber egg or something.

[disassembler]

I'll take 19 and 18. Get well @grahamc!

[disassembler]

And 17 and 16 as well :)

[grahamc]

I just merged all the outstanding PRs, thank you so much. Eight more to go! WOW.

[grahamc]

Please send future PRs to http://github.com/nixos/nix-pills

I've made a hydra jobset: https://hydra.nixos.org/jobset/nix-pills/master

I've also made a PR to put the pills on the website: NixOS/nixos-homepage#153

We're in the home stretch. Unfortunately porting a pill is quite typing-heavy, and am not ready to do that yet.

[disassembler]

Got 15 and 14

[Ericson2314]

FYI I checked some boxes for things I saw PRs for.

[disassembler]

I'll grab 12 and 13 too.

[grahamc]

We're done 😻 nice work, everyone! Thank you so much! Now to get it on the website :)

[domenkozar]

Great job - sorry I couldn't help and thanks to everyone taking part - every improvement to documentation is high appreciated. <3