Re: [Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
The Go language toolkit has the nice approach, similar as in doxygen
or javadoc, based on theory that if documentation is close to code, it
will be easier to keep it correct. I believe it is working great. It
would be nice if a similar tool was created for Nix, making it easy to
automatically extract comments from Nix files/expressions into an easy
to read and navigate document/website. Then, I'd suppose the OP's
question would become moot, as the answer would be obvious - to put
explanations in comments in derivation code. The added benefit would
be that to read the docs for basic functions (like lib.extend), one
wouldn't have to grep & browse through the sources.
/Mateusz.
On Fri, Jun 17, 2016 at 3:34 PM, Daniel Hlynskyi wrote:
> Write a blog post. Though it is hard to maintain blog post content over
> time, ask yourself "how long am I able to maintain this knowledge? Who
> should be responsible for verifying this manual in with future changes?"
>
> People expect manuals to be consistent with software. Every time I find
> errors in docs, I am step away from using it. From this perspective
> blogposts and wiki are better place to contribute unmaintained knowledge -
> we don't expect them to be always correct.
>
> Make tags, so google can find your article with "quake nix".
>
> Just IMO, but critique accepted.
>
> 8 квіт. 2016 1:36 пп, користувач "Nikolay Amiantov" написав:
>
>> Hi,
>>
>> I want to add some documentation on how to use our ioquake3 derivation.
>> This brings me to question on _where_ should I actually add it. Right
>> now we have:
>>
>> 1. Nix manual: completely unrelated to my topic;
>> 2. NixOS manual: primarily describes services and not packages and is
>> NixOS-oriented, while my article can be of interest to Quake-playing Nix
>> users in general;
>> 3. nixpkgs manual: oriented at developers and packagers (as it itself
>> points out).
>>
>> I would have added my article to the wiki, but AFAIK it's generally
>> decided to get rid of it. So, where should I place articles like this? I
>> would describe the general class of such documentation as "user-oriented
>> nixpkgs manual".
>>
>> I have some other documentation articles in mind that I would like to
>> write later (e.g. on steam-run), which go to the same category (I don't
>> mean "games" ^_^).
>>
>> On 04/08/2016 12:28 PM, Nikolay Amiantov wrote:
>> > I play ioquake3 successfully. It needs the following to work:
>> >
>> > 1. Extract pak0.pk3 file from the original Quake 3 Arena.
>> > 2. Use Nix script like this:
>> >
>> > { nixpkgs ? import { } }:
>> >
>> > let
>> > paks = nixpkgs.stdenv.mkDerivation {
>> > name = "quake3-arena";
>> > pak0 = ./baseq3/pak0.pk3; # Replace this with path to your file
>> > buildCommand = ''
>> > install -D -m644 $pak0 $out/baseq3/pak0.pk3;
>> > '';
>> > };
>> > in nixpkgs.quake3wrapper {
>> > paks = [ paks nixpkgs.quake3pointrelease ];
>> > }
>> >
>> > 3. Run `nix-build` on it: `nix-build script.nix`
>> > 4. `result/bin/quake3` would run the game.
>> >
>> > This probably needs to be added to our manual and/or improved somehow.
>>
>> --
>> Nikolay.
>> ___
>> 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 mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
Write a blog post. Though it is hard to maintain blog post content over
time, ask yourself "how long am I able to maintain this knowledge? Who
should be responsible for verifying this manual in with future changes?"
People expect manuals to be consistent with software. Every time I find
errors in docs, I am step away from using it. From this perspective
blogposts and wiki are better place to contribute unmaintained knowledge -
we don't expect them to be always correct.
Make tags, so google can find your article with "quake nix".
Just IMO, but critique accepted.
8 квіт. 2016 1:36 пп, користувач "Nikolay Amiantov" написав:
> Hi,
>
> I want to add some documentation on how to use our ioquake3 derivation.
> This brings me to question on _where_ should I actually add it. Right
> now we have:
>
> 1. Nix manual: completely unrelated to my topic;
> 2. NixOS manual: primarily describes services and not packages and is
> NixOS-oriented, while my article can be of interest to Quake-playing Nix
> users in general;
> 3. nixpkgs manual: oriented at developers and packagers (as it itself
> points out).
>
> I would have added my article to the wiki, but AFAIK it's generally
> decided to get rid of it. So, where should I place articles like this? I
> would describe the general class of such documentation as "user-oriented
> nixpkgs manual".
>
> I have some other documentation articles in mind that I would like to
> write later (e.g. on steam-run), which go to the same category (I don't
> mean "games" ^_^).
>
> On 04/08/2016 12:28 PM, Nikolay Amiantov wrote:
> > I play ioquake3 successfully. It needs the following to work:
> >
> > 1. Extract pak0.pk3 file from the original Quake 3 Arena.
> > 2. Use Nix script like this:
> >
> > { nixpkgs ? import { } }:
> >
> > let
> > paks = nixpkgs.stdenv.mkDerivation {
> > name = "quake3-arena";
> > pak0 = ./baseq3/pak0.pk3; # Replace this with path to your file
> > buildCommand = ''
> > install -D -m644 $pak0 $out/baseq3/pak0.pk3;
> > '';
> > };
> > in nixpkgs.quake3wrapper {
> > paks = [ paks nixpkgs.quake3pointrelease ];
> > }
> >
> > 3. Run `nix-build` on it: `nix-build script.nix`
> > 4. `result/bin/quake3` would run the game.
> >
> > This probably needs to be added to our manual and/or improved somehow.
>
> --
> Nikolay.
> ___
> 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] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
> RST is best. I don't get this attitude. Documentation has to be easy to write, or very few people will do it. At least 90% of developers know and prefer Markdown over everything else, even if the syntax has fundamental flaws. On Sat, Apr 16, 2016, at 01:44 AM, Anderson Torres wrote: > 2016-04-15 13:54 GMT-03:00 Profpatsch : > > On 16-04-09 04:10pm, Anderson Torres wrote: > >> I prefer to start a documentation project, like the FreeBSD > >> Handbook[1]. It could contain some in-project documentation for every > >> module too. > > > > I proposed a Cookbook a while ago, akin to the Puppet one > > http://www.puppetcookbook.com/ > > > > We could write that in Asciidoc or Markdown (or rst). > > RST is best. > > > > > -- > > Proudly written in Mutt with Vim on NixOS. > > Q: Why is this email five sentences or less? > > A: http://five.sentenc.es > > May take up to five days to read your message. If it’s urgent, call me. > ___ > 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] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
2016-04-15 13:54 GMT-03:00 Profpatsch : > On 16-04-09 04:10pm, Anderson Torres wrote: >> I prefer to start a documentation project, like the FreeBSD >> Handbook[1]. It could contain some in-project documentation for every >> module too. > > I proposed a Cookbook a while ago, akin to the Puppet one > http://www.puppetcookbook.com/ > > We could write that in Asciidoc or Markdown (or rst). RST is best. > > -- > Proudly written in Mutt with Vim on NixOS. > Q: Why is this email five sentences or less? > A: http://five.sentenc.es > May take up to five days to read your message. If it’s urgent, call me. ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
On 16-04-09 04:10pm, Anderson Torres wrote: > I prefer to start a documentation project, like the FreeBSD > Handbook[1]. It could contain some in-project documentation for every > module too. I proposed a Cookbook a while ago, akin to the Puppet one http://www.puppetcookbook.com/ We could write that in Asciidoc or Markdown (or rst). -- Proudly written in Mutt with Vim on NixOS. Q: Why is this email five sentences or less? A: http://five.sentenc.es May take up to five days to read your message. If it’s urgent, call me. ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
I prefer to start a documentation project, like the FreeBSD
Handbook[1]. It could contain some in-project documentation for every
module too.
[1] https://www.freebsd.org/doc/handbook/
2016-04-09 12:48 GMT-03:00 zimbatm :
> Good question. The wiki seems like the right place to me but it's read-only
> now.
>
> On Fri, 8 Apr 2016 at 11:36 Nikolay Amiantov wrote:
>>
>> Hi,
>>
>> I want to add some documentation on how to use our ioquake3 derivation.
>> This brings me to question on _where_ should I actually add it. Right
>> now we have:
>>
>> 1. Nix manual: completely unrelated to my topic;
>> 2. NixOS manual: primarily describes services and not packages and is
>> NixOS-oriented, while my article can be of interest to Quake-playing Nix
>> users in general;
>> 3. nixpkgs manual: oriented at developers and packagers (as it itself
>> points out).
>>
>> I would have added my article to the wiki, but AFAIK it's generally
>> decided to get rid of it. So, where should I place articles like this? I
>> would describe the general class of such documentation as "user-oriented
>> nixpkgs manual".
>>
>> I have some other documentation articles in mind that I would like to
>> write later (e.g. on steam-run), which go to the same category (I don't
>> mean "games" ^_^).
>>
>> On 04/08/2016 12:28 PM, Nikolay Amiantov wrote:
>> > I play ioquake3 successfully. It needs the following to work:
>> >
>> > 1. Extract pak0.pk3 file from the original Quake 3 Arena.
>> > 2. Use Nix script like this:
>> >
>> > { nixpkgs ? import { } }:
>> >
>> > let
>> > paks = nixpkgs.stdenv.mkDerivation {
>> > name = "quake3-arena";
>> > pak0 = ./baseq3/pak0.pk3; # Replace this with path to your file
>> > buildCommand = ''
>> > install -D -m644 $pak0 $out/baseq3/pak0.pk3;
>> > '';
>> > };
>> > in nixpkgs.quake3wrapper {
>> > paks = [ paks nixpkgs.quake3pointrelease ];
>> > }
>> >
>> > 3. Run `nix-build` on it: `nix-build script.nix`
>> > 4. `result/bin/quake3` would run the game.
>> >
>> > This probably needs to be added to our manual and/or improved somehow.
>>
>> --
>> Nikolay.
>> ___
>> 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 mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev
Re: [Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
Good question. The wiki seems like the right place to me but it's read-only
now.
On Fri, 8 Apr 2016 at 11:36 Nikolay Amiantov wrote:
> Hi,
>
> I want to add some documentation on how to use our ioquake3 derivation.
> This brings me to question on _where_ should I actually add it. Right
> now we have:
>
> 1. Nix manual: completely unrelated to my topic;
> 2. NixOS manual: primarily describes services and not packages and is
> NixOS-oriented, while my article can be of interest to Quake-playing Nix
> users in general;
> 3. nixpkgs manual: oriented at developers and packagers (as it itself
> points out).
>
> I would have added my article to the wiki, but AFAIK it's generally
> decided to get rid of it. So, where should I place articles like this? I
> would describe the general class of such documentation as "user-oriented
> nixpkgs manual".
>
> I have some other documentation articles in mind that I would like to
> write later (e.g. on steam-run), which go to the same category (I don't
> mean "games" ^_^).
>
> On 04/08/2016 12:28 PM, Nikolay Amiantov wrote:
> > I play ioquake3 successfully. It needs the following to work:
> >
> > 1. Extract pak0.pk3 file from the original Quake 3 Arena.
> > 2. Use Nix script like this:
> >
> > { nixpkgs ? import { } }:
> >
> > let
> > paks = nixpkgs.stdenv.mkDerivation {
> > name = "quake3-arena";
> > pak0 = ./baseq3/pak0.pk3; # Replace this with path to your file
> > buildCommand = ''
> > install -D -m644 $pak0 $out/baseq3/pak0.pk3;
> > '';
> > };
> > in nixpkgs.quake3wrapper {
> > paks = [ paks nixpkgs.quake3pointrelease ];
> > }
> >
> > 3. Run `nix-build` on it: `nix-build script.nix`
> > 4. `result/bin/quake3` would run the game.
> >
> > This probably needs to be added to our manual and/or improved somehow.
>
> --
> Nikolay.
> ___
> 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
