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
On 04/16/2016 12:11 PM, Jakob Gillich wrote: >> 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. Let me repeat again: write the great content in *any format* that suits you, file a PR, and /cc me. I'll convert it or ensure some other way... --Vladimir smime.p7s Description: S/MIME Cryptographic Signature ___ 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
On 04/10/2016 02:51 AM, Nikolay Amiantov wrote:
> how often does our documentation on the website[1] update? [...]
nixos.org/{nixpkgs,nixos}/manual are for the current stable release.
They show the commit directly under the title. IIRC they are updated
automatically, probably when updating channels.
--Vladimir
smime.p7s
Description: S/MIME Cryptographic Signature
___
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
Somewhat unrelated questions: how often does our documentation on the website[1] update? It is tied now to the unstable releases, if I understand correctly. What about NixOS documentation? Do we have documentation for stable releases online? [1]: https://nixos.org/nixpkgs/manual/ -- Nikolay. On 04/08/2016 03:12 PM, Vladimír Čunát wrote: > On 04/08/2016 12:36 PM, Nikolay Amiantov wrote: >> 3. nixpkgs manual: oriented at developers and packagers (as it itself >> points out). > > There is some user documentation in the nixpkgs manual already, e.g. > about installing Haskell and TeX Live packages. Currently we don't have > any better place, I believe. I also recently changed the introduction of > the manual to indicate it isn't only for devs. > > --Vladimir > > ___ 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
I haven't read this handbook before unfortunately -- can you please summarize how does it differ from our NixOS manual? -- Nikolay. On 04/09/2016 10:10 PM, 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. > > > [1] https://www.freebsd.org/doc/handbook/ ___ 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
Re: [Nix-dev] User-oriented nixpkgs documentation
On 04/08/2016 12:36 PM, Nikolay Amiantov wrote: > 3. nixpkgs manual: oriented at developers and packagers (as it itself > points out). There is some user documentation in the nixpkgs manual already, e.g. about installing Haskell and TeX Live packages. Currently we don't have any better place, I believe. I also recently changed the introduction of the manual to indicate it isn't only for devs. --Vladimir smime.p7s Description: S/MIME Cryptographic Signature ___ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
[Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)
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
