I think the explanation for how propagation works is too detailed for a user manual. I think the first thing in that section should really just be a couple examples of when propagatedBuildInputs is needed and not needed. I think the detailed explanation of exactly how dependencies are propagated and in what way should be saved for a different document. Maybe a wiki page?
I do not think that the Nixpkgs manual is a user manual; for a long time it was called Nixpkgs development manual, but it also has accumulated some user-oriented notes that had no better place to go.
And of course there are notes for maintainers of normal packages there, and there are things for people who debug core parts (e.g. when wanting to fix cross-compilation to minor platforms), and these are also not always well-separated.
But this approach takes the problem out of the papercut scope, I guess…
The manual structure has been bothering me for a long time as well. For starters, the separation between Nix, NixOS, and nixpkgs - normal users don’t care about which part a given thing technically belongs to, they just want to know how to do a thing.
We should probably have a different documentation division: something like user manual, development manual, internals reference. Each manual could then, for example, have highlighted/marked sections with “this section only applies on NixOS” or “this section only applies of you’re using nixpkgs”, and so on.
Anyhow, this does veer off into more detailed discussion We should probably have a dedicated thread for this? Not sure if Discourse has a ‘split thread’ feature, to move out these two posts and link to the new thread.
Is it a technical problem (eg. “what stuff can we use that supports highlighted sections like this”) or rather an organizational problem (eg. “this is a big job, where do we start without breaking the manuals for users or going out of sync”)?
Also, are there any existing issue threads or such that contain the previous discussion(s)? I haven’t run across them.
Most of these were offline at nixcon and such, it started with first Nix gatherings 2014 when I invited Mikey Ariel (one of the organizers of WriteTheDocs conference).
The gist is that docbook is for writing books, if you want to scatter documentation around in different formats it’s actually a lot of work since tooling is decades old.
Not to mention for SEO you want each documentation section to be separate page, as Google doesn’t like huge dumps of text as it’s a SEO trick. Once you have multi-page docs, you need search…
So there’s a deadlock: docbook is what we have and it seems to be semantically superior, while there’s little effort to write the tooling to write such structured documentation.
I’ve been strong proponent of asciidoc (which actually translates to docbook) and https://asciidoctor.org/, we’ll actually be releading a tool for documentation of NixOS projects soon backed by this tooling.
As for Nix community I think as always, someone enthusiastic should take the lead and I highly doubt anyone will be against better docs
Looking through the AsciiDoctor documentation, I can’t find any way to define marked “this only applies to NixOS” sections. All the block types seem to be pre-defined and non-customizable. Am I missing something?
Could you explain better what’s your objective? You can do imports, so that way you can organize and reuse snippets of documentation. There are also tags, so you can say asciidoc --tags foo and it will conditionally include or exclude per tag.
Some months ago In my spare time I’ve built an automatic converter from docbook to Sphinx ReSt format, It is almost complete, but it lacks support for other document inclusion and the annotated source examples, unfortunately sphinx has no support for those. If it can be of any help, I can resurrect it
What would that look like in asciidoc syntax, though? As I understand it, it would require re-specifying the icon and text for every single such block, which is not practical.
What I’m looking for is some sort of way to have reusable wrapper elements, similar to what MDX can do. So that you can simply mark something as “this is NixOS-only”, and the actual markup (what informational text to show, what formatting to use, etc.) is handled elsewhere in a consistent manner.