| 29 Jun 2023 |
 pennae | nope, ids must be unique within te entire manual | 16:51:01 |
 Robert Hensing (roberth) | well that's an artificial restriction then | 16:51:16 |
| pennae | kind of. otherwise we won't be able to [](#link) them without having to duplicate knowledge of where they are | 16:51:33 |
| Robert Hensing (roberth) | most documentation systems do need the location to be part of the identifier, so it'd be a bit weird not to do that | 16:52:41 |
| pennae | it definitely was not an artificial restriction in docbook, and for maintainability's sake we're very opposed to dropping it | 16:52:47 |
| Robert Hensing (roberth) | yeah it's yet another project | 16:53:04 |
| pennae | In reply to @roberthensing:matrix.org
most documentation systems do need the location to be part of the identifier, so it'd be a bit weird not to do that arguably that just makes the location part of the id, which does not solve the underlying problem :/ | 16:53:49 |
| pennae | the mismatch from input files to output files that we've now inherited from docbook complicates this even more | 16:55:37 |
 alejandrosame | 
Download Screenshot from 2023-06-29 18-05-37.png | 17:11:12 |
| alejandrosame | Sharing a screenshot of the WIP work on the nixpkgs manual Python section. | 17:12:09 |
 fricklerhandwerk | Here's another piece for the survey regarding contributor workflow: https://floxdev.com/blog/nixpkgs-contribution | 22:37:45 |
| 30 Jun 2023 |
 sterni | why can’t nobody at flox proofread such articles (if they are even wise to publish in that context)? Couple of inaccuracies and multiple things that are wrong presented as facts. | 07:36:05 |
|  jakob joined the room. | 08:33:28 |
|  ruby changed their profile picture. | 14:02:47 |
 Sandro 🐧 | FYI https://github.com/NixOS/nixpkgs/pull/240754 | 16:15:47 |
| sterni | pennae: maybe every md file for the manual could have an unique prefix assigned to it (e.g. haskell- for haskell.section.md). The md toolchain would then prefix every reference in the markdown file with that unless it is already prefixed. That would ensure unique anchors as long as the prefixes are unique.
Problem is of course that anchors would be changed, maybe we'd need to generously whitelist existing ones.
| 16:16:14 |
| sterni | * pennae: maybe every md file for the manual could have an unique prefix assigned to it (e.g. haskell- for haskell.section.md). The md toolchain would then prefix every reference in the markdown file with that unless it is already prefixed. That would ensure unique anchors as long as the prefixes are unique.
Problem is of course that anchors would be changed, maybe we'd need to generously whitelist existing ones. Still seems better than uuids.
Personally I'd also just be fine with a linter that checks for link uniqueness
| 16:16:37 |
| pennae | that's an option too, though we'd have to include the path of the file from the doc root instead of just the file name itself (and that can get pretty long) | 16:42:55 |
| pennae | nrd already checks for uniqueness and throws an error on duplicates, but that's a pretty bad experience. and the anchors that are likely to be problematic are exactly the ones that don't convey meaning | 16:43:37 |
| sterni | pennae: just have a list | 16:55:11 |
| sterni | well then just have meaningful anchors :) | 16:55:47 |
| pennae | In reply to @sternenseemann:systemli.org
well then just have meaningful anchors :) tell docs authors that D: | 16:58:10 |
| pennae | like. te python chapter has a section with the id faq | 16:58:52 |
| pennae | * like. the python chapter has a section with the id faq | 16:59:05 |
| pennae | that has been the in-html id for at least a very long time, possibly forever | 16:59:23 |
| sterni | I think checking for such things in the manual build is the best solution | 17:02:52 |
| sterni | it may always fail, after all | 17:02:59 |
| pennae | we do check, and it has failed in the past | 17:04:26 |
| pennae | at least now it can tell you where shit broke instead of having relaxng slap you with entirely incorrect error locations and messages that aren't worth the photons they're imprinted on | 17:05:41 |
| 1 Jul 2023 |
| pennae | nixdoc changes for nixpkgs markdowning are merged 🥳 | 12:42:41 |
