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.
My first idea was: Why not use Markdown? Everyone can use it!
But after checking out AsciiDoc, there are good reasons to use that over Markdown for documentation.
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.