Nixpkgs: Nixpkgs manual TOC lacks language-specific subsections

[nh2]

https://nixos.org/nixpkgs/manual/#chap-language-support now simply says e.g.

15.9. Haskell

Before it showed lots of useful sub-sections to quickly jump to the part you were interested in.

1. Does anybody know if this reduction of subsections in the table of contents was on purpose, or perhapse accidental due to some verison upgrade?
2. How can we get the subsections back?

[worldofpeace]

cc @FRidh maybe?

[FRidh]

Back in October I reorganized the manual. Those changes were backported to 19.09 so it should not come as a surprise.

Anyway, part of it was to reduce the main TOC size because of the noise in it. Certain sections are significantly larger (Haskell, Python) than others producing also many more entries. It doesn't make sense then to bother a reader with all kinds of details of a specific builder at that point when they are still navigating. Those sections should have their own TOC's but good luck fixing that.

Given there was not much feedback it is how it is now. I think the Builders part may be split into multiple parts because of its size and the level of nesting, but really, its the mixture of types of information that's the problem here.

Note the same changes were made at the time to the NixOS manual.

[7c6f434c]

Given there was not much feedback it is how it is now. I think the Builders part may be split into multiple parts because of its size and the level of nesting, but really, its the mixture of types of information that's the problem here.

Note that in the process you merged two different parts into the single Builders section (and some of the merged sections are not about builders at all) — on the other hand, the parts being discussed are indeed reasonably related to builders (and still not found with the current ToC)

On the other hand, what is the value of smaller ToC?

[nh2]

I understand it is handy to have an overview on the different programming languages like this

so that you can quickly find the one you are interested in.

But it is not handy that after you've found your language, you lose all ability find the right section.

Those sections should have their own TOC's but good luck fixing that.

If it is difficult to make sub-table-of-contents, what is your judgement on making the main table of contents collapsible at that subsection level, similar to Github's <details>?

[FRidh]

If it is difficult to make sub-table-of-contents, what is your judgement on making the main table of contents collapsible at that subsection level, similar to Github's

?

Honestly I have no idea. IMO both are fine to have although I would prefer sub TOC's.

[peti]

Furthermore, 95dfbe2d632b71a72634d2d65e3f738f500ee5ce renamed the Haskell subsection of the manual:

-# User's Guide to the Haskell Infrastructure
+# Haskell

This change breaks everyone's expectation that https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure would be a stable link. :-(

[stale[bot]]

Nixpkgs stale bot info

[peti]

Haskell documentation is now at https://haskell4nix.readthedocs.io/.

[nh2]

@peti Doesn't that have to be linked somewhere in the manual?

https://nixos.org/manual/nixpkgs/unstable/#haskell now has its subsections back but does not include your link.

[peti]

I committed changes to the documentation that replace the text with a reference to the new location, but apparently it took a while for those updates to make it onto the web site. It looks like https://nixos.org/manual/nixpkgs/unstable/#haskell has the correct contents now.

[FRidh]

What is the motivation to move the docs away from the project? Because the link changed? Or because it will cover parts that are outside of Nixpkgs?