nixos/doc/manual: In the preface, add link to #chap-contributing #108481
Conversation
| @@ -14,9 +14,6 @@ xlink:href="https://github.com/NixOS/nixpkgs">Nixpkgs</link> repository. | |||
| <screen> | |||
| <prompt>$ </prompt>cd /path/to/nixpkgs | |||
| <prompt>$ </prompt>nix-build nixos/release.nix -A manual.x86_64-linux | |||
| <prompt>$ </prompt>xdg-open ./result/share/doc/nixos/index.html | |||
There was a problem hiding this comment.
I don't know if I like this change, since this would only work in Linux OS, and even them not all of them (not necessary everyone has xdg-open installed). macOS users are out of lucky.
There was a problem hiding this comment.
@thiagokokada well, this is the NixOS manual, and as such this is linux only. or do i misunderstand something here?
There was a problem hiding this comment.
my reasoning was that having something that works at most places, or can be made to work easily, is much better than not having something that can be easily copy-pasted.
otherwise it's just a relative path that the browser cannot even open in its URL bar when copy-pasted.
There was a problem hiding this comment.
Well, for example I could open in a browser terminal like Elinks (but my default browser is a graphical one). BTW, I said the part of macOS because someone maybe working in improving the NixOS manual from their macs.
I really prefer how it was before, because you don't have to assume anything about the user setup.
There was a problem hiding this comment.
ok, i'm new here, so i won't push this, i'll revert that part.
i still believe, though, that it's an improvement. people can still just ignore the xdg-open and copy-paste the ./result/ part, just like before.
and besides, the entire manual seems to be built assuming x86_64-linux in the previous line. that's much more platform dependent than the new xdg-open. it would be nice to get rid of that. e.g. by some uname -foo, or something like that. i was surprised by that when i first built the manual, but luckily it was matching my host.
There was a problem hiding this comment.
another suggestion: replace xdg-open with [preferred browser].
There was a problem hiding this comment.
i still believe, though, that it's an improvement. people can still just ignore the xdg-open and copy-paste the ./result/ part, just like before.
But now you're assuming that people know what xdg-open does. If they don't know that this is a "program to open files", they may even assume that this is something related to the manual build process.
another suggestion: replace xdg-open to [preferred browser].
I quite like how it is, it is very clear what is happening. Even preferred browser is not ideal considering some of the more strange setups out there (Emacs for example).
BTW, I am just a collaborator of some reviews here, my word is not final so if you want to keep xdg-open and wait for another reviewer it is fine too.
Turned the freetext suggestion about opening the build output into a copy-pastable xdg-open line. Renamed title to 'Contributing to this manual'.
attila-lendvai
force-pushed
the
attila-manual
branch
from
6c911f2
to
d5b7f7b
Compare
|
@thiagokokada ok, i've reverted the xdg-open part. |
|
@thiagokokada sorry about the repeated review request, it was by accident. |
|
@grahamc @jonringer could one of you take a look at this? |
|
ofborg built manual successfully |
|
congrats @attila-lendvai on your first contribution to NixOS/nixpkgs 🎊 |
Motivation for this change
it took me long minutes to find out where the sources are for this document.
Things done
in the preface i added a link to #chap-contributing
turned the freetext suggestion about opening the build output into a copy-pastable xdg-open line
renamed chapter title to 'Contributing to this manual'
tested the build on x86_64 nixos
Built on platform(s)
Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
Tested compilation of all pkgs that depend on this change using
nix-shell -p nixpkgs-review --run "nixpkgs-review wip"Tested execution of all binary files (usually in
./result/bin/)Determined the impact on package closure size (by running
nix path-info -Sbefore and after)Ensured that relevant documentation is up to date
Fits CONTRIBUTING.md.