[Nix-dev] [RFC] Generating documentation from nixpkgs (markdown files) with pandoc (Was: Real documentation, aka "Let's kill the wiki")

[Matthias Beyer]

I created a showcase on how to generate documentation from the nixpkgs
tree:

https://github.com/matthiasbeyer/nixpkgs/tree/pandoc-documentation

Note:

1) The documentation is still generated from .md files, not by
   parsing .nix files. This could be changed, but isn't trivial.

2) I did not focus on release the full power of pandoc. I create a
   showcase, I want to show how it could work and that it actually
   works.

3) To run:
nix-shell shell.nix # Pulls Pandoc in a nix-shell
make # calls pandoc

4) I did not style anything, I did not create some files, there
   are already some .md files in the nixpkgs tree, I just use
   them to create some .html output

5) As said in 4), I create .html output. PDF files could be
  created in a similar way.

This is an request for comments/commits.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Domen Kožar]

You have to think about the audience.

In general following should cover us:

- tutorial (how do I get quickly update to date on X topic)
- user guide (how does a specific feature work)
- reference (functions and what they do)

Currently that's all bundled throughout the manual (and wiki).

Domen

On Wed, Nov 18, 2015 at 5:01 PM, Karsten Gebbert  wrote:

> Hajo Möller  writes:
>
> > As mentioned in another thread, Rok Garbas proposed to remove the wiki
> > and replace it with "real documentation". I fully support this.
> >
> > To follow up on this proposal I suggest we decide what real
> > documentation should look like, so let us reiterate his main points:
> >
> > "Why do we write documentation?"
> > Is it just to remind ourselves about details, or also for helping the
> > readers reach an advanced level of understanding? It should be the both.
> >
> > "There needs to be a clear definition of how documentation is written."
> > We already have coding conventions, but there is no clear how-to for
> > writing good documentation. Maybe (professional) technical writers can
> > chime in here?
> >
> > "Documentation should teach, not tell."
> > As Rok said, handing somebody who is learning a new language a
> > dictionary would not help them learn.
> > It is not possible for us to get an immediate reaction to pinpoint the
> > exact moment our documentation becomes incomprehensible, having our
> > documentation follow a well-defined pattern should help here.
> > This also means we need to hold our users' hands, leading them
> > step-by-step through complex procedures instead of directly presenting
> > results.
> >
> > "You should never tell somebody to read the source."
> > Even though the source code should be self-explanatory (and often is,
> > see the files in nixpkgs/lib for well-commented examples), having real
> > documentation in the form of a manual helps keep everything in the same
> > place. This way there can be a single location where users come to when
> > they are lost.
> >
> > "The manual is good, but not made for beginners."
> > Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> > Although I generally agree, I am not sure where to place those tutorials
> > and what they should cover. Should they be on people's blogs, aggregated
> > in the planet.nixos.org?
> >
> > "Let's kill the wiki, it's not documentation but an abomination."
> > Unmoderated wikis tend to contain outdated or just plain wrong
> > information, it is then arguably better to have no documentation at all
> > than a wiki teaching the wrong things. Also, developers asking (possibly
> > misunderstanding) users to fix the wiki could lead to a scenario where
> > the blind lead the blind.
>
> I think that it would be good to loosely decide on the sections a good
> manual/documentation should consist of. This might help structuring the
> effort
> and break up tasks in meaningful chunks.
>
> I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind
> of),
> and it would be good to approach the task with its quality and
> comprehensiveness
> as the long-term goal.
>
> From the top of my head, there are multiple aspects to it:
>
> * Cookbook (how do I do XYZ?) e.g.
>   - setting up a Desktop environment
>   - setting up ...
>   - setting up a development environment
>   - detailed guides on developing with in language XYZ
>   - overriding/customizing packages
>   - 
> * nix-* command reference (man pages would probably already suffice)
> * nixpkgs & library (w/ inline docs)
>   - modules
>   - contributors guide
>   - function reference?
> * nix, the language
>   - reference manual
>   - useful snippets?
>
> So, if there is an effort to aggregate information in one place, we could
> split
> up the task according to such a list of sections and work more or less
> independently in branches.
>
> Best,
>
> karsten
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[deCube.net | Danny Wilson]

On 18 nov. 2015, at 16:00, Augustin Borsu  wrote:

> What about having a documentation field in pkgs that allows for markdown?
> Can't get closer to the code than that.


This.
Documentation that’s seperated from code always rots.  Even when you hire 
technical writers...

Related talk from a Technical writer about how Google fixed their docs:  
https://youtu.be/EnB8GtPuauw?t=6m18s

> 
> Also generating an html doc of all the options of a package,
> their default value and maybe a comment by the author of the package
> and an example config would go a lng way.
> 
> Le 18/11/15 15:04, Hajo Möller a écrit :
>> As mentioned in another thread, Rok Garbas proposed to remove the wiki
>> and replace it with "real documentation". I fully support this.
>> 
>> To follow up on this proposal I suggest we decide what real
>> documentation should look like, so let us reiterate his main points:
>> 
>> "Why do we write documentation?"
>> Is it just to remind ourselves about details, or also for helping the
>> readers reach an advanced level of understanding? It should be the both.
>> 
>> "There needs to be a clear definition of how documentation is written."
>> We already have coding conventions, but there is no clear how-to for
>> writing good documentation. Maybe (professional) technical writers can
>> chime in here?
>> 
>> "Documentation should teach, not tell."
>> As Rok said, handing somebody who is learning a new language a
>> dictionary would not help them learn.
>> It is not possible for us to get an immediate reaction to pinpoint the
>> exact moment our documentation becomes incomprehensible, having our
>> documentation follow a well-defined pattern should help here.
>> This also means we need to hold our users' hands, leading them
>> step-by-step through complex procedures instead of directly presenting
>> results.
>> 
>> "You should never tell somebody to read the source."
>> Even though the source code should be self-explanatory (and often is,
>> see the files in nixpkgs/lib for well-commented examples), having real
>> documentation in the form of a manual helps keep everything in the same
>> place. This way there can be a single location where users come to when
>> they are lost.
>> 
>> "The manual is good, but not made for beginners."
>> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
>> Although I generally agree, I am not sure where to place those tutorials
>> and what they should cover. Should they be on people's blogs, aggregated
>> in the planet.nixos.org?
>> 
>> "Let's kill the wiki, it's not documentation but an abomination."
>> Unmoderated wikis tend to contain outdated or just plain wrong
>> information, it is then arguably better to have no documentation at all
>> than a wiki teaching the wrong things. Also, developers asking (possibly
>> misunderstanding) users to fix the wiki could lead to a scenario where
>> the blind lead the blind.
>> 
>> 
> 
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Karsten Gebbert]

Hajo Möller  writes:

> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.
>
> To follow up on this proposal I suggest we decide what real
> documentation should look like, so let us reiterate his main points:
>
> "Why do we write documentation?"
> Is it just to remind ourselves about details, or also for helping the
> readers reach an advanced level of understanding? It should be the both.
>
> "There needs to be a clear definition of how documentation is written."
> We already have coding conventions, but there is no clear how-to for
> writing good documentation. Maybe (professional) technical writers can
> chime in here?
>
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> It is not possible for us to get an immediate reaction to pinpoint the
> exact moment our documentation becomes incomprehensible, having our
> documentation follow a well-defined pattern should help here.
> This also means we need to hold our users' hands, leading them
> step-by-step through complex procedures instead of directly presenting
> results.
>
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.
>
> "The manual is good, but not made for beginners."
> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> Although I generally agree, I am not sure where to place those tutorials
> and what they should cover. Should they be on people's blogs, aggregated
> in the planet.nixos.org?
>
> "Let's kill the wiki, it's not documentation but an abomination."
> Unmoderated wikis tend to contain outdated or just plain wrong
> information, it is then arguably better to have no documentation at all
> than a wiki teaching the wrong things. Also, developers asking (possibly
> misunderstanding) users to fix the wiki could lead to a scenario where
> the blind lead the blind.

I think that it would be good to loosely decide on the sections a good
manual/documentation should consist of. This might help structuring the effort
and break up tasks in meaningful chunks.

I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind of),
and it would be good to approach the task with its quality and comprehensiveness
as the long-term goal.

From the top of my head, there are multiple aspects to it:

* Cookbook (how do I do XYZ?) e.g.
  - setting up a Desktop environment
  - setting up ...
  - setting up a development environment
  - detailed guides on developing with in language XYZ
  - overriding/customizing packages
  - 
* nix-* command reference (man pages would probably already suffice)
* nixpkgs & library (w/ inline docs)
  - modules
  - contributors guide
  - function reference? 
* nix, the language
  - reference manual
  - useful snippets?

So, if there is an effort to aggregate information in one place, we could split
up the task according to such a list of sections and work more or less
independently in branches.

Best,

karsten
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [RFC] Generating documentation from nixpkgs (markdown files) with pandoc

[Peter Simons]

Hi folks,

this may not be obvious, so I felt I should better point out that the
Haskell part of the User Manual is already generated from Markdown. See
doc/haskell-users-guide.md and doc/default.nix for further details.

Best regards,
Peter

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] Documentation on the Genode port

[Emery Hemingway]

I've started writing some documentation on the Nix to Genode port, and I have 
an 
explaination for some of the demo during Nixcon. Its fringe stuff but I'll try 
and keep 
some notes together if someone else wants to do some cross platform stuff.

https://ehmry.github.io/

Cheers,
Emery


signature.asc
Description: Digital signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] Hamburg NixOS Meetup

[Pascal Wittmann]

Hi there,

are there any fellow Nixers in Hamburg who want to meet up from time to
time? I thought about creating a meetup.com page for organization but
wanted to check if there is some interest first.

Regards,
Pascal



signature.asc
Description: OpenPGP digital signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [RFC] Generating documentation from nixpkgs (markdown files) with pandoc (Was: Real documentation, aka "Let's kill the wiki")

[Domen Kožar]

I've once experimented and ported nixpkgs manual to
http://static.domenkozar.com/nixpkgs-manual-sphinx-exp/

But there doesn't seem to be of a much interest to make documentation more
approachable (something we did with github for code)

On Wed, Nov 18, 2015 at 6:47 PM, Matthias Beyer 
wrote:

> I created a showcase on how to generate documentation from the nixpkgs
> tree:
>
> https://github.com/matthiasbeyer/nixpkgs/tree/pandoc-documentation
>
> Note:
>
> 1) The documentation is still generated from .md files, not by
>parsing .nix files. This could be changed, but isn't trivial.
>
> 2) I did not focus on release the full power of pandoc. I create a
>showcase, I want to show how it could work and that it actually
>works.
>
> 3) To run:
> nix-shell shell.nix # Pulls Pandoc in a nix-shell
> make # calls pandoc
>
> 4) I did not style anything, I did not create some files, there
>are already some .md files in the nixpkgs tree, I just use
>them to create some .html output
>
> 5) As said in 4), I create .html output. PDF files could be
>   created in a similar way.
>
> This is an request for comments/commits.
>
> --
> Mit freundlichen Grüßen,
> Kind regards,
> Matthias Beyer
>
> Proudly sent with mutt.
> Happily signed with gnupg.
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Hamburg NixOS Meetup

[Hajo Möller]

Sure, let's do this.
How about meeting irregularly for good coffee and a snack around midday?

-- 
Regards,
Hajo Möller
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Documentation on the Genode port

[Tim Cuthbertson]

Thanks, Emery - I'm a big fan of both Nix (obviously) and also Genode,
so I have been very pleased to see your lightning talk and now this
writeup :)

Cheers,
 - Tim.

On Thu, Nov 19, 2015 at 5:37 AM, Emery Hemingway  wrote:
> I've started writing some documentation on the Nix to Genode port, and I have 
> an
> explaination for some of the demo during Nixcon. Its fringe stuff but I'll 
> try and keep
> some notes together if someone else wants to do some cross platform stuff.
>
> https://ehmry.github.io/
>
> Cheers,
> Emery
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Hamburg NixOS Meetup

[Alexander Flatter]

I'm in!

On Wed, Nov 18, 2015, at 07:43 PM, Pascal Wittmann wrote:
> Hi there,
> 
> are there any fellow Nixers in Hamburg who want to meet up from time to
> time? I thought about creating a meetup.com page for organization but
> wanted to check if there is some interest first.
> 
> Regards,
> Pascal
> 
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
> Email had 1 attachment:
> + signature.asc
>   1k (application/pgp-signature)
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Hydra.nixos.org problems

[Domen Kožar]

stan appears to be out of disk space http://hydra.nixos.org/build/27896328

On Tue, Nov 17, 2015 at 5:05 PM, Vladimír Čunát  wrote:

> Hi,
> We're getting lots of Hydra errors saying:
> Aborted: cannot connect to ‘root@kenny’: Connection closed by
> 131.180.119.71
>
> It seems to be killing lots of builds randomly.
>
>
> Incidentally, it might be nice if the fact that one build slave is
> unreachable wouldn't lead to the jobs being aborted. They could be
> retried, perhaps getting lucky to be assigned to a working machine.
>
>
> Vladimir
>
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [PATCH] pulseaudio: Add support for package configuration files.

[Jookia]

On Wed, Nov 18, 2015 at 10:02:33AM +0100, Luca Bruno wrote:
> I hope somehow will review this. Personally I'd prefer if you made a
> pull request on github.

While github allows use of its services for registered users
without nonfree javascript, unfortunately it doesn't allow you to register
without it. In my tests I got as far as email validation. Nitpicky I know, but
it'd really make me feel uncomfortable using a service that disallows people to
join in without using only free software.

I've heard that the mailing list is okay for patches, and given the speed of
things I'm fine if it takes longer to get a patch reviewed or in.

I don't have a good solution to fix this problem, or even if others acknowledge
that it's a problem. I wonder if there's any review tools that support a github
bridge that someone could set up. It doesn't look like it from first glance.

Jookia.
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Oliver Charles Talk

[Oliver Charles]

Hi Stewart,

Glad you liked the talk! I will be tidying things up - probably tomorrow -
and publishing a blog post on this, and I should be able to have an
accompanying Github repository of relevant code. Keep an eye on
https://ocharles.org.uk/blog (there are RSS feeds if you use a feed
reader). I'll also get my blog added to the Planet before posting the
article.

Thanks for mentioning boot-nix - while I'm not writing ClojureScript any
more, this will certainly come in handy if I ever come back to it :)

Regards,
Ollie

On Tue, Nov 17, 2015 at 3:56 PM stewart mackenzie 
wrote:

> Hi Oliver,
>
> I'd greatly appreciate it if you could share your cleaned up
> deployment nix scripts for fynder.
>
> You're doing some really cool stuff there which is currently what I'm
> building out here:
>
> github.com/fractalide/nixos-infrastructure
>
> btw I've got a boot-nix which is a boot-clj.com task which enumerates
> clojure/script dependencies then downloads them, hopefully others
> might be interested in that.
>
> https://github.com/fractalide/boot-nix
>
> Thanks for giving that talk!
>
> /sjm
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] [call for] Release manager for Hydra

[Domen Kožar]

Hi all,

at NixCon we had a discussion about having releases for Hydra. Mainly to
well, know what git commit is considered stable.

There seemed to be quite some interest, but to make that happen we need
someone to volunteer to be a release manager. They would be doing QA that
the release works and make sure changelog, docs, etc are updated.

Is anyone willing to step up and help the community?

Cheers, Domen
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [PATCH] pulseaudio: Add support for package configuration files.

[Luca Bruno]

On 17/11/2015 21:39, Jookia wrote:
> In a fashion like udev's support, this patch allows configurations from 
> packages
> to be merged in to directories for PulseAudio to read from. Currently 
> supported
> directories are the alsa-mixer mdoule's profile-sets and paths.
>
> This is accomplished by patching PulseAudio to read directories from 
> environment
> variables globally defined by NixOS rather from the data path in the Nix 
> store.
> Modules that support it (such as the alsa module) can still be configured at
> runtime to use specific paths, this just changes the default paths.
>
> The environment variables are only used if they're defined, as such the 
> previous
> behaviour can be reverted to if the variables are unset or NixOS isn't 
> running.
> ---
>  nixos/modules/config/pulseaudio.nix   | 43 +
>  pkgs/servers/pulseaudio/custom-dirs.patch | 52 
> +++
>  pkgs/servers/pulseaudio/default.nix   |  2 +-
>  3 files changed, 96 insertions(+), 1 deletion(-)
>  create mode 100644 pkgs/servers/pulseaudio/custom-dirs.patch
>
> diff --git a/nixos/modules/config/pulseaudio.nix 
> b/nixos/modules/config/pulseaudio.nix
> index 2ebc612..bad4bf3 100644
> --- a/nixos/modules/config/pulseaudio.nix
> +++ b/nixos/modules/config/pulseaudio.nix
> @@ -52,6 +52,37 @@ let
>  }
>'');
>  
> +  # Create a directory full of configuration files for PulseAudio to use for
> +  # various modules. Packages are scanned similiar how udev does it.
> +  moduleEnvVars = {
> +PA_ALSA_PATHS_DIR = "${moduleConf}/alsa-paths";
> +PA_ALSA_PROFILE_SETS_DIR = "${moduleConf}/alsa-profiles";
> +  };
> +  moduleConf = stdenv.mkDerivation {
> +name = "pulseaudio-moduleconf";
> +
> +preferLocalBuild = true;
> +allowSubstitutes = false;
> +
> +buildCommand = ''
> +  mkdir -p $out/{alsa-profiles,alsa-paths}
> +  shopt -s nullglob
> +  set +o pipefail
> +
> +  function copy_dir() {
> +for j in $1/$2/*; do
> +  echo "Copying $i to $out/$3/$(basename $j)"
> +  cat $j > $out/$3/$(basename $j)
> +done
> +  }
> +
> +  for i in ${toString cfg.packages}; do
> +echo "Adding configuration for package $i"
> +copy_dir $i/usr/share/pulseaudio/alsa-mixer profile-sets 
> alsa-profiles
> +copy_dir $i/usr/share/pulseaudio/alsa-mixer paths alsa-paths
> +  done
> +'';
> +  };
>  in {
>  
>options = {
> @@ -96,6 +127,17 @@ in {
>  '';
>};
>  
> +  packages = mkOption {
> +type = types.listOf types.path;
> +description = ''
> +  List of packages containing additional PulseAudio configuration.
> +  All files found in the following directories:
> +  
> pkg/usr/share/lib/pulseaudio/alsa-mixer/profile-sets
> +  
> pkg/usr/share/lib/pulseaudio/alsa-mixer/paths
> +  will be included.
> +'';
> +  };
> +
>package = mkOption {
>  type = types.package;
>  default = pulseaudioLight;
> @@ -130,6 +172,7 @@ in {
>};
>  
>hardware.pulseaudio.configFile = mkDefault 
> "${cfg.package}/etc/pulse/default.pa";
> +  environment.sessionVariables = moduleEnvVars;
>  }
>  
>  (mkIf cfg.enable {
> diff --git a/pkgs/servers/pulseaudio/custom-dirs.patch 
> b/pkgs/servers/pulseaudio/custom-dirs.patch
> new file mode 100644
> index 000..00e2ee7
> --- /dev/null
> +++ b/pkgs/servers/pulseaudio/custom-dirs.patch
> @@ -0,0 +1,52 @@
> +diff -Naur pulseaudio-7.0/src/modules/alsa/alsa-mixer.c 
> pulseaudio-7.0.new/src/modules/alsa/alsa-mixer.c
> +--- pulseaudio-7.0/src/modules/alsa/alsa-mixer.c 2015-09-15 
> 14:46:06.0 +1000
>  pulseaudio-7.0.new/src/modules/alsa/alsa-mixer.c 2015-11-18 
> 12:58:33.490001078 +1100
> +@@ -2521,10 +2521,11 @@
> + }
> + 
> + static const char *get_default_paths_dir(void) {
> ++char *env = getenv("PA_ALSA_PATHS_DIR");
> + if (pa_run_from_build_tree())
> + return PA_SRCDIR "/modules/alsa/mixer/paths/";
> + else
> +-return PA_ALSA_PATHS_DIR;
> ++return (env ? env : PA_ALSA_PATHS_DIR);
> + }
> + 
> + pa_alsa_path* pa_alsa_path_new(const char *paths_dir, const char *fname, 
> pa_alsa_direction_t direction) {
> +@@ -4347,6 +4348,7 @@
> + pa_alsa_profile *p;
> + pa_alsa_mapping *m;
> + pa_alsa_decibel_fix *db_fix;
> ++char *env;
> + char *fn;
> + int r;
> + void *state;
> +@@ -4392,9 +4394,10 @@
> + if (!fname)
> + fname = "default.conf";
> + 
> ++env = getenv("PA_ALSA_PROFILE_SETS_DIR");
> + fn = pa_maybe_prefix_path(fname,
> +   pa_run_from_build_tree() ? PA_SRCDIR 
> "/modules/alsa/mixer/profile-sets/" :
> +-  PA_ALSA_PROFILE_SETS_DIR);
> ++  (env ? env : PA_ALSA_PROFILE_SETS_DIR));
> + 
> + r = pa_config_parse(fn, NULL, items, NULL, ps);
> + pa_xfree(fn);
> +diff 

Re: [Nix-dev] Pass arguments to 'required' configs

[Sergey Mironov]

Nicolas, this solution makes sense if I understand how to include
private modules to local configuration. (We are discussing this in a
separate thread).

Regards,
Sergey

2015-11-17 17:55 GMT+03:00 Nicolas Pierron :
> Hi Sergey,
>
> If you are not using the proxy_port and proxy_host values for
> selecting the modules, I suggest you use the module system instead.
> This means that your previous example would become something like the
> example below. This solution is a bit more verbose, but you might be
> able to introspect these options with nixos-option command line tool
> and NixUI.
>
> // configuration.nix
> {
>   require = [
> /etc/nixos/configuration.nix
> ./include/global_bash_aliases.nix
>   ];
>
>   custom.go.proxy.port = 4343;
>   custom.go.proxy.host = "myproxy.local";
>   …
> }
>
> // ./include/global_bash_aliases.nix
>
> { config, pkgs, lib, ... } :
>
> with lib;
> {
>   options = {
> custom.go.proxy.port = mkOption {
>   default = 4242;
>   example = 4343;
>   type = types.uniq types.int;
>   description = ''
> port number used by the goproxy shell alias command.
>   '';
> };
>
> custom.go.proxy.host = mkOption {
>   example = "example.com";
>   type = types.uniq types.str;
>   description = ''
> host name used by the goproxy shell alias command.
>   '';
> };
>   };
>
>   config = {
> environment = {
>
>   extraInit = with config.custom.go.proxy ''
>  alias goproxy "nc ${port} ${host}
>   '';
> };
>   };
> }
>
>
> On Tue, Nov 17, 2015 at 2:17 PM, Sergey Mironov  wrote:
>> Hi. This is a follow-up to my previous letter about Private NixOS modules.
>>
>> Another thing I am missing is the ability to pass arguments to
>> 'required' configuration modules. Below is the illustration of the
>> idea. Could you please give me some advice on this?
>>
>> Regards,
>> Sergey
>>
>>
>> // configuration.nix
>>
>> {config, pkgs, ...}:
>> let
>>   proxy_port = "4343";
>>   proxy_host = "myproxy.local";
>> in
>> {
>>   require = [
>> /etc/nixos/hardware-configuration.nix
>> ..
>> (withArguments ./include/global_bash_aliases.nix { inherit
>> proxy_port  proxy_host; })
>> ..
>>   ];
>>  ...
>>
>> }
>>
>>
>> //./include/global_bash_aliases.nix
>>
>> { proxy_port, proxy_host} :
>> { config, pkgs, ... } :
>> {
>>   environment = rec {
>>
>> extraInit = ''
>>alias goproxy "nc ${proxy_port} ${proxy_host}
>> '';
>>   };
>>
>> }
>> ___
>> nix-dev mailing list
>> nix-dev@lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
>
> --
> Nicolas Pierron
> http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [nix-dev] private NixOS modules

[Nicolas Pierron]

Hi Sergey,

We have a some documenation in the NixOS Manual [1] which explains how
to do that.  To make it short, your configuration.nix file should have
an import attribute which is a list of additional modules that you
want to include.
So if you file configuration.nix looks something like (a), you want to
convert it to something similar to (b)

** (a):
{
  services.openssh.enable = true = …;
  …
}

** (b):

{
  imports = [ ./custom-service.nix ];
  services.openssh.enable = true = …;
  …
}

[1] http://nixos.org/nixos/manual/index.html#sec-modularity

On Wed, Nov 18, 2015 at 8:14 AM, Sergey Mironov  wrote:
> Nicolas, I didn't know about NIXOS_EXTRA_MODULE_PATH, thanks.
> Could you explain other possible solution in a bit more details? How
> can we include modified module list in configuration.nix?
>
> Regards,
> Sergey
>
> 2015-11-17 17:43 GMT+03:00 Nicolas Pierron :
>> Hi Sergey,
>>
>> I think you can set the NIXOS_EXTRA_MODULE_PATH [1] environment
>> variable to achieve that.
>> Otherwise, you can change your configuration.nix file to always
>> include your new module list, and to include your own real-config.nix
>>
>> [1] 
>> https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/eval-config.nix#L30
>>
>>
>> On Tue, Nov 17, 2015 at 2:04 PM, Sergey Mironov  wrote:
>>> Hi. I'd like to write a couple of NixOS modules which probably don't
>>> look meaningful for large audience. Normally, we keep modules in
>>> nixpkgs/nixos/modules directory and list them in module-list.nix file.
>>> In my case, I'd like to put module in a private place (which is my git
>>> repo which keeps nixpkgs as a Git submodule). Is it possible to
>>> 'include' them in the public list to make them accessible from
>>> per-system.nix files?
>>>
>>> As a result, I'd like to be able to write in configuration.nix
>>> something like the following:
>>>
>>> services.my-custom-service = {
>>>   enable = true;
>>>   ...
>>> }
>>>
>>> without including expression for my-custom-service in the public tree.
>>>
>>> Regards,
>>> Sergey
>>> ___
>>> nix-dev mailing list
>>> nix-dev@lists.science.uu.nl
>>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>>
>>
>>
>> --
>> Nicolas Pierron
>> http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/



-- 
Nicolas Pierron
http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [nix-dev] private NixOS modules

[Sergey Mironov]

Oh, Thanks. I really should re-read the manual :)

Sergey

2015-11-18 12:16 GMT+03:00 Nicolas Pierron :
> Hi Sergey,
>
> We have a some documenation in the NixOS Manual [1] which explains how
> to do that.  To make it short, your configuration.nix file should have
> an import attribute which is a list of additional modules that you
> want to include.
> So if you file configuration.nix looks something like (a), you want to
> convert it to something similar to (b)
>
> ** (a):
> {
>   services.openssh.enable = true = …;
>   …
> }
>
> ** (b):
>
> {
>   imports = [ ./custom-service.nix ];
>   services.openssh.enable = true = …;
>   …
> }
>
> [1] http://nixos.org/nixos/manual/index.html#sec-modularity
>
> On Wed, Nov 18, 2015 at 8:14 AM, Sergey Mironov  wrote:
>> Nicolas, I didn't know about NIXOS_EXTRA_MODULE_PATH, thanks.
>> Could you explain other possible solution in a bit more details? How
>> can we include modified module list in configuration.nix?
>>
>> Regards,
>> Sergey
>>
>> 2015-11-17 17:43 GMT+03:00 Nicolas Pierron :
>>> Hi Sergey,
>>>
>>> I think you can set the NIXOS_EXTRA_MODULE_PATH [1] environment
>>> variable to achieve that.
>>> Otherwise, you can change your configuration.nix file to always
>>> include your new module list, and to include your own real-config.nix
>>>
>>> [1] 
>>> https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/eval-config.nix#L30
>>>
>>>
>>> On Tue, Nov 17, 2015 at 2:04 PM, Sergey Mironov  wrote:
 Hi. I'd like to write a couple of NixOS modules which probably don't
 look meaningful for large audience. Normally, we keep modules in
 nixpkgs/nixos/modules directory and list them in module-list.nix file.
 In my case, I'd like to put module in a private place (which is my git
 repo which keeps nixpkgs as a Git submodule). Is it possible to
 'include' them in the public list to make them accessible from
 per-system.nix files?

 As a result, I'd like to be able to write in configuration.nix
 something like the following:

 services.my-custom-service = {
   enable = true;
   ...
 }

 without including expression for my-custom-service in the public tree.

 Regards,
 Sergey
 ___
 nix-dev mailing list
 nix-dev@lists.science.uu.nl
 http://lists.science.uu.nl/mailman/listinfo/nix-dev
>>>
>>>
>>>
>>> --
>>> Nicolas Pierron
>>> http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
>
>
>
> --
> Nicolas Pierron
> http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [nix-dev] private NixOS modules

[Sergey Mironov]

Nicolas, I didn't know about NIXOS_EXTRA_MODULE_PATH, thanks.
Could you explain other possible solution in a bit more details? How
can we include modified module list in configuration.nix?

Regards,
Sergey

2015-11-17 17:43 GMT+03:00 Nicolas Pierron :
> Hi Sergey,
>
> I think you can set the NIXOS_EXTRA_MODULE_PATH [1] environment
> variable to achieve that.
> Otherwise, you can change your configuration.nix file to always
> include your new module list, and to include your own real-config.nix
>
> [1] https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/eval-config.nix#L30
>
>
> On Tue, Nov 17, 2015 at 2:04 PM, Sergey Mironov  wrote:
>> Hi. I'd like to write a couple of NixOS modules which probably don't
>> look meaningful for large audience. Normally, we keep modules in
>> nixpkgs/nixos/modules directory and list them in module-list.nix file.
>> In my case, I'd like to put module in a private place (which is my git
>> repo which keeps nixpkgs as a Git submodule). Is it possible to
>> 'include' them in the public list to make them accessible from
>> per-system.nix files?
>>
>> As a result, I'd like to be able to write in configuration.nix
>> something like the following:
>>
>> services.my-custom-service = {
>>   enable = true;
>>   ...
>> }
>>
>> without including expression for my-custom-service in the public tree.
>>
>> Regards,
>> Sergey
>> ___
>> nix-dev mailing list
>> nix-dev@lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
>
> --
> Nicolas Pierron
> http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Pass arguments to 'required' configs

[Sergey Mironov]

Sorry, I just noticed that you have modified my example radically.
Looks like this is the answer to my question regarding custom modules,
thanks!

Sergey

2015-11-18 12:11 GMT+03:00 Sergey Mironov :
> Nicolas, this solution makes sense if I understand how to include
> private modules to local configuration. (We are discussing this in a
> separate thread).
>
> Regards,
> Sergey
>
> 2015-11-17 17:55 GMT+03:00 Nicolas Pierron :
>> Hi Sergey,
>>
>> If you are not using the proxy_port and proxy_host values for
>> selecting the modules, I suggest you use the module system instead.
>> This means that your previous example would become something like the
>> example below. This solution is a bit more verbose, but you might be
>> able to introspect these options with nixos-option command line tool
>> and NixUI.
>>
>> // configuration.nix
>> {
>>   require = [
>> /etc/nixos/configuration.nix
>> ./include/global_bash_aliases.nix
>>   ];
>>
>>   custom.go.proxy.port = 4343;
>>   custom.go.proxy.host = "myproxy.local";
>>   …
>> }
>>
>> // ./include/global_bash_aliases.nix
>>
>> { config, pkgs, lib, ... } :
>>
>> with lib;
>> {
>>   options = {
>> custom.go.proxy.port = mkOption {
>>   default = 4242;
>>   example = 4343;
>>   type = types.uniq types.int;
>>   description = ''
>> port number used by the goproxy shell alias command.
>>   '';
>> };
>>
>> custom.go.proxy.host = mkOption {
>>   example = "example.com";
>>   type = types.uniq types.str;
>>   description = ''
>> host name used by the goproxy shell alias command.
>>   '';
>> };
>>   };
>>
>>   config = {
>> environment = {
>>
>>   extraInit = with config.custom.go.proxy ''
>>  alias goproxy "nc ${port} ${host}
>>   '';
>> };
>>   };
>> }
>>
>>
>> On Tue, Nov 17, 2015 at 2:17 PM, Sergey Mironov  wrote:
>>> Hi. This is a follow-up to my previous letter about Private NixOS modules.
>>>
>>> Another thing I am missing is the ability to pass arguments to
>>> 'required' configuration modules. Below is the illustration of the
>>> idea. Could you please give me some advice on this?
>>>
>>> Regards,
>>> Sergey
>>>
>>>
>>> // configuration.nix
>>>
>>> {config, pkgs, ...}:
>>> let
>>>   proxy_port = "4343";
>>>   proxy_host = "myproxy.local";
>>> in
>>> {
>>>   require = [
>>> /etc/nixos/hardware-configuration.nix
>>> ..
>>> (withArguments ./include/global_bash_aliases.nix { inherit
>>> proxy_port  proxy_host; })
>>> ..
>>>   ];
>>>  ...
>>>
>>> }
>>>
>>>
>>> //./include/global_bash_aliases.nix
>>>
>>> { proxy_port, proxy_host} :
>>> { config, pkgs, ... } :
>>> {
>>>   environment = rec {
>>>
>>> extraInit = ''
>>>alias goproxy "nc ${proxy_port} ${proxy_host}
>>> '';
>>>   };
>>>
>>> }
>>> ___
>>> nix-dev mailing list
>>> nix-dev@lists.science.uu.nl
>>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>>
>>
>>
>> --
>> Nicolas Pierron
>> http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] TexLive wiki page

[Matthias Beyer]

On 18-11-2015 08:29:52, Karsten Gebbert wrote:
> IMHO, the Github wiki should probably be that place, and the workflow
> markdown/rst/org -> pandoc -> pdf/html (& possibly gh-pages). It makes it easy
> to contribute via $EDITOR + git or a convenient web interface.
> 
> My $0.02 :)
> 

I'd vote against github wiki. It is just a mess IMHO and is for taking
notes, not for documentation.

Though I'd vote for a markdown/rst -> git+pandoc -> html/pdf solution
(not org, as this is [kindof] bound to an editor). I'd be happy
with pandoc, but I'd vote against gitit, btw! I find it too bulkyish
and I'd prefer github as web UI, but this is debatable as well.

Maybe we can have a sprint at 32C3 for this.

I see one problem: The documentation is not located near to the code
it documents. We should include the documentation (as .md or .rst
files) within the nixpkgs repository and compile it with pandoc from
tree to html/pdf.

Maybe we can set something up right now? I think I can put some effort
into this at the weekend and get something basic working, shouldn't be
too much to do, actually.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Domen Kožar]

I fully agree, and probably others too, but someone has to step up and lead
that effort :)

On Wed, Nov 18, 2015 at 3:04 PM, Hajo Möller  wrote:

> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.
>
> To follow up on this proposal I suggest we decide what real
> documentation should look like, so let us reiterate his main points:
>
> "Why do we write documentation?"
> Is it just to remind ourselves about details, or also for helping the
> readers reach an advanced level of understanding? It should be the both.
>
> "There needs to be a clear definition of how documentation is written."
> We already have coding conventions, but there is no clear how-to for
> writing good documentation. Maybe (professional) technical writers can
> chime in here?
>
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> It is not possible for us to get an immediate reaction to pinpoint the
> exact moment our documentation becomes incomprehensible, having our
> documentation follow a well-defined pattern should help here.
> This also means we need to hold our users' hands, leading them
> step-by-step through complex procedures instead of directly presenting
> results.
>
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.
>
> "The manual is good, but not made for beginners."
> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> Although I generally agree, I am not sure where to place those tutorials
> and what they should cover. Should they be on people's blogs, aggregated
> in the planet.nixos.org?
>
> "Let's kill the wiki, it's not documentation but an abomination."
> Unmoderated wikis tend to contain outdated or just plain wrong
> information, it is then arguably better to have no documentation at all
> than a wiki teaching the wrong things. Also, developers asking (possibly
> misunderstanding) users to fix the wiki could lead to a scenario where
> the blind lead the blind.
>
>
> --
> Regards,
> Hajo Möller
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Matthias Beyer]

On 18-11-2015 15:40:43, Domen Kožar wrote:
> I fully agree, and probably others too, but someone has to step up and lead
> that effort :)
> 

As said in the other thread, I will try to get something basic working
this weekend, if I have enough time. I'm not sure whether this falls
into "step up and lead that effort".

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] planet.nixos.org - a rss aggregation feed - add yourself

[Rok Garbas]

Hi,

I would like to ask you to add yourself to the `planet.nixos.org` to have
a channel where all the thoughts on nixos are aggregated.

Fork the below repository, add yourself to the list and send a pull request:


https://github.com/NixOS/nixos-org-configurations/blob/master/nixos-org/planet-feeds.nix

Thank you.


--
Rok Garbas - http://www.garbas.si


signature.asc
Description: signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] planet.nixos.org - a rss aggregation feed - add yourself

[Matthias Beyer]

On 18-11-2015 14:20:42, Rok Garbas wrote:
> I would like to ask you to add yourself to the `planet.nixos.org` to have
> a channel where all the thoughts on nixos are aggregated.
> 
> Fork the below repository, add yourself to the list and send a pull request:
> 
> 
> https://github.com/NixOS/nixos-org-configurations/blob/master/nixos-org/planet-feeds.nix
> 
> Thank you.

Hey,

Is there a review-process involved? Because my english skills are not
that good and I wonder whether you want to keep a certain level of
professionality on the planet?

I think about adding myself, I own a blog where I write about
non-nixos-topics, too, but I have rss feeds for tags, so "nixos" and
"nix" tags can be tracked easily.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] TexLive wiki page

[Rok Garbas]

Quoting Matthias Beyer (2015-11-18 14:23:41)
> On 18-11-2015 08:29:52, Karsten Gebbert wrote:
> > IMHO, the Github wiki should probably be that place, and the workflow
> > markdown/rst/org -> pandoc -> pdf/html (& possibly gh-pages). It makes it 
> > easy
> > to contribute via $EDITOR + git or a convenient web interface.
> > 
> > My $0.02 :)
> > 
> 
> I'd vote against github wiki. It is just a mess IMHO and is for taking
> notes, not for documentation.
> 
> Though I'd vote for a markdown/rst -> git+pandoc -> html/pdf solution
> (not org, as this is [kindof] bound to an editor). I'd be happy
> with pandoc, but I'd vote against gitit, btw! I find it too bulkyish
> and I'd prefer github as web UI, but this is debatable as well.
> 
> Maybe we can have a sprint at 32C3 for this.
> 
> I see one problem: The documentation is not located near to the code
> it documents. We should include the documentation (as .md or .rst
> files) within the nixpkgs repository and compile it with pandoc from
> tree to html/pdf.
> 
> Maybe we can set something up right now? I think I can put some effort
> into this at the weekend and get something basic working, shouldn't be
> too much to do, actually.
> 

Hi,

Just to clarify to not introduce confusion about my talk from NixCon.

- wiki will not go away any time soon. definetly not before we have some
  alternative documentation i was talking about.

- tools which we use dont matter. instead of spending time on figuring out
  which format to choose and which framework to use to generate docs, rather
  write a tutorial about something. we need more content and not more tools.
  at least that is how i see the problem.

i would much rather see a discussion what to write and not how to write.




--
Rok Garbas - http://www.garbas.si


signature.asc
Description: signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] [call for] Release manager for Hydra

[Matthias Beyer]

On 18-11-2015 12:23:30, Peter Simons wrote:
> Domen Kožar writes:
> 
>  > We need someone to volunteer to be a release manager. They would be
>  > doing QA that the release works and make sure changelog, docs, etc
>  > are updated.
> 
> Also, we need a Hydra module for NixOS so that NixOS users can set-up
> Hydra easily through their configuration.nix file. Hydra provides such a
> module, of course, but the fact that it's living in a separate repository
> complicates matters a bit, particularly for newbies who are just getting
> started and who might try out NixOS mostly because of Hydra. We cannot
> expect them to mess with imports and fetchgit and channels and whatnot on
> their first day.
> 

Big +1 on this. I'd love to run my own hydra, but the lack of a simple

services.hydra.enable = true;

-ish configuration keeps me away from this.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Matthias Beyer]

On 18-11-2015 15:04:30, Hajo Möller wrote:
> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.

Me too.

> 
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.

Keeping everything in one place is a good idea, though we really
should be careful about nix (language), nix (pkg manager) and nixos
mixing. These confused me the first time I dived into the topic.

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] Real documentation, aka "Let's kill the wiki"

[Hajo Möller]

As mentioned in another thread, Rok Garbas proposed to remove the wiki
and replace it with "real documentation". I fully support this.

To follow up on this proposal I suggest we decide what real
documentation should look like, so let us reiterate his main points:

"Why do we write documentation?"
Is it just to remind ourselves about details, or also for helping the
readers reach an advanced level of understanding? It should be the both.

"There needs to be a clear definition of how documentation is written."
We already have coding conventions, but there is no clear how-to for
writing good documentation. Maybe (professional) technical writers can
chime in here?

"Documentation should teach, not tell."
As Rok said, handing somebody who is learning a new language a
dictionary would not help them learn.
It is not possible for us to get an immediate reaction to pinpoint the
exact moment our documentation becomes incomprehensible, having our
documentation follow a well-defined pattern should help here.
This also means we need to hold our users' hands, leading them
step-by-step through complex procedures instead of directly presenting
results.

"You should never tell somebody to read the source."
Even though the source code should be self-explanatory (and often is,
see the files in nixpkgs/lib for well-commented examples), having real
documentation in the form of a manual helps keep everything in the same
place. This way there can be a single location where users come to when
they are lost.

"The manual is good, but not made for beginners."
Rok suggests to have tutorials teaching the basics of Nix and NixOS.
Although I generally agree, I am not sure where to place those tutorials
and what they should cover. Should they be on people's blogs, aggregated
in the planet.nixos.org?

"Let's kill the wiki, it's not documentation but an abomination."
Unmoderated wikis tend to contain outdated or just plain wrong
information, it is then arguably better to have no documentation at all
than a wiki teaching the wrong things. Also, developers asking (possibly
misunderstanding) users to fix the wiki could lead to a scenario where
the blind lead the blind.


-- 
Regards,
Hajo Möller

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] planet.nixos.org - a rss aggregation feed - add yourself

[Rok Garbas]

Quoting Matthias Beyer (2015-11-18 14:31:03)
> On 18-11-2015 14:20:42, Rok Garbas wrote:
> > I would like to ask you to add yourself to the `planet.nixos.org` to have
> > a channel where all the thoughts on nixos are aggregated.
> > 
> > Fork the below repository, add yourself to the list and send a pull request:
> > 
> > 
> > https://github.com/NixOS/nixos-org-configurations/blob/master/nixos-org/planet-feeds.nix
> > 
> > Thank you.
> 
> Hey,
> 
> Is there a review-process involved? Because my english skills are not
> that good and I wonder whether you want to keep a certain level of
> professionality on the planet?
> 

no review process, since it just a simple aggregation. if you want somebody to
review your blogposts you can always ask on irc channel. i think many will help
gladly (i know i would).

if non-nixos related blogposts we occur we will kindly ask the person to
fix/stop it.

> I think about adding myself, I own a blog where I write about
> non-nixos-topics, too, but I have rss feeds for tags, so "nixos" and
> "nix" tags can be tracked easily.
> 

yes. adding only subset of your blog that talks about nixos/nix would be
desired.


--
Rok Garbas - http://www.garbas.si


signature.asc
Description: signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] TexLive wiki page

[Matthias Beyer]

On 18-11-2015 14:41:42, Rok Garbas wrote:
> i would much rather see a discussion what to write and not how to write.
> 

So you would like to see more blog posts, more tutorials and more
stuff like that?

So, something like my blog series about switching to nixos[0]? Or what
are your ideas here?

[0]: 
https://beyermatthias.de/blog/2015/01/10/my-experience-when-switching-to-nixos-part-1/

-- 
Mit freundlichen Grüßen,
Kind regards,
Matthias Beyer

Proudly sent with mutt.
Happily signed with gnupg.


signature.asc
Description: PGP signature
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Real documentation, aka "Let's kill the wiki"

[Augustin Borsu]

What about having a documentation field in pkgs that allows for markdown?
Can't get closer to the code than that.

Also generating an html doc of all the options of a package,
their default value and maybe a comment by the author of the package
and an example config would go a lng way.

Le 18/11/15 15:04, Hajo Möller a écrit :
> As mentioned in another thread, Rok Garbas proposed to remove the wiki
> and replace it with "real documentation". I fully support this.
>
> To follow up on this proposal I suggest we decide what real
> documentation should look like, so let us reiterate his main points:
>
> "Why do we write documentation?"
> Is it just to remind ourselves about details, or also for helping the
> readers reach an advanced level of understanding? It should be the both.
>
> "There needs to be a clear definition of how documentation is written."
> We already have coding conventions, but there is no clear how-to for
> writing good documentation. Maybe (professional) technical writers can
> chime in here?
>
> "Documentation should teach, not tell."
> As Rok said, handing somebody who is learning a new language a
> dictionary would not help them learn.
> It is not possible for us to get an immediate reaction to pinpoint the
> exact moment our documentation becomes incomprehensible, having our
> documentation follow a well-defined pattern should help here.
> This also means we need to hold our users' hands, leading them
> step-by-step through complex procedures instead of directly presenting
> results.
>
> "You should never tell somebody to read the source."
> Even though the source code should be self-explanatory (and often is,
> see the files in nixpkgs/lib for well-commented examples), having real
> documentation in the form of a manual helps keep everything in the same
> place. This way there can be a single location where users come to when
> they are lost.
>
> "The manual is good, but not made for beginners."
> Rok suggests to have tutorials teaching the basics of Nix and NixOS.
> Although I generally agree, I am not sure where to place those tutorials
> and what they should cover. Should they be on people's blogs, aggregated
> in the planet.nixos.org?
>
> "Let's kill the wiki, it's not documentation but an abomination."
> Unmoderated wikis tend to contain outdated or just plain wrong
> information, it is then arguably better to have no documentation at all
> than a wiki teaching the wrong things. Also, developers asking (possibly
> misunderstanding) users to fix the wiki could lead to a scenario where
> the blind lead the blind.
>
>

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

[Nix-dev] Yet Another idea About the Wiki

[Martin Vahi]

I'm one of those people, who is new to Nix and
is trying to learn it. What regards to the idea
of killing the wiki, then I suggest that You
just make a wiki that is editable only to
the people, who have been with the project for
a long time and know, what they are writing about.

Once upon a time, years ago, at one of my jobs
we solved the problem so that we had an internal
wiki that only the core developers could edit
and then the rest, PDF/static-HTML/whatever that went
to the end users, was automatically generated
from that wiki by the release team. The generated
documentation was bundled with the application,
like at the old times on Windows, where each
application had a Help menu with documentation, except
that in stead of the Windows CHM-files the application
launched the default web browser with a local file
URL to the static, bundled, HTML.

It worked fine. Everyone were happy, even the
ones that wanted to print PDF-s.

There were 2 types of documentation: the "tutorial"
and the API doc. In the case of the API doc we used
special syntax that was used by the application
for showing the documentation dynamically, at its
proprietary IDE.

We actually made quite many iterations before
coming up with the wiki based solution and the
end result worked like a charm. :-D

Of course, the difficulty is the modification of the
wiki software, but, life is tough, so that just has
to be lived with.

With a hope of being useful,
martin.v...@softf1.com

___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev

Re: [Nix-dev] Yet Another idea About the Wiki

[Benno Fünfstück]

Hi,

I don't see how this proposal is better than just placing the documentation
in some markup format in the nixpkgs repository itself.  Compared to your
proposed approach, that would have at least two advantages:

* documentation is at least near to the code, making it easier to sync it
with changes.
* even non - core devs can edit the documentation, but their contributions
have to be reviewed by a core dev.

Regards,
Benno

Martin Vahi  schrieb am Do., 19. Nov. 2015 03:58:

> I'm one of those people, who is new to Nix and
> is trying to learn it. What regards to the idea
> of killing the wiki, then I suggest that You
> just make a wiki that is editable only to
> the people, who have been with the project for
> a long time and know, what they are writing about.
>
> Once upon a time, years ago, at one of my jobs
> we solved the problem so that we had an internal
> wiki that only the core developers could edit
> and then the rest, PDF/static-HTML/whatever that went
> to the end users, was automatically generated
> from that wiki by the release team. The generated
> documentation was bundled with the application,
> like at the old times on Windows, where each
> application had a Help menu with documentation, except
> that in stead of the Windows CHM-files the application
> launched the default web browser with a local file
> URL to the static, bundled, HTML.
>
> It worked fine. Everyone were happy, even the
> ones that wanted to print PDF-s.
>
> There were 2 types of documentation: the "tutorial"
> and the API doc. In the case of the API doc we used
> special syntax that was used by the application
> for showing the documentation dynamically, at its
> proprietary IDE.
>
> We actually made quite many iterations before
> coming up with the wiki based solution and the
> end result worked like a charm. :-D
>
> Of course, the difficulty is the modification of the
> wiki software, but, life is tough, so that just has
> to be lived with.
>
> With a hope of being useful,
> martin.v...@softf1.com
>
> ___
> nix-dev mailing list
> nix-dev@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
___
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev