NixOS/nixpkgs

Port Nix Pills in to a document produced by Nixpkgs

grahamc opened this issue · 33 comments

grahamc commented

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:

(thank you by the way)

Todo:

ixxie commented

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

nixy commented

@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 commented

@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 commented

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 commented

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."

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 commented

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

NeQuissimus commented

Oooh, nice! Thank you @lethalman !

  • 🎉1
ixxie commented

I'll grab 5 and 6 for now :)

lheckemann commented

I'll take 7.

ixxie commented

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 commented

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 commented

What about <code> vs <programlisting>?

grahamc commented

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 commented

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

grahamc commented

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 commented

@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 commented

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.

  • 👍1
grahamc commented

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

lheckemann commented

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

ankhers commented

I can grab 8 and 9.

ankhers commented

10 and 11

grahamc commented

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 commented

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

disassembler commented

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

disassembler commented

And 17 and 16 as well :)

grahamc commented

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

grahamc commented

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 commented

Got 15 and 14

Ericson2314 commented

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

disassembler commented

I'll grab 12 and 13 too.

grahamc commented

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

domenkozar commented

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

  • ❤️1