RFC 0072 FCP, Switch to CommonMark for documentation

Announcements
1

The Final Comment Period for RFC 0072 has started and, barring any blocking issues, will be merged after 2020-10-30. Your opinions, comments, and approvals are welcome!

https://github.com/NixOS/rfcs/pull/72

9 Likes
2
3

Can’t wait to finally retake my habit of clarifying drive-by contributions.

1 Like
4

Yes!
This will help nullify the feedback on my PR documentation: add documentation for buildMaven by fzakaria · Pull Request #100660 · NixOS/nixpkgs · GitHub to move it to docbook :laughing:

5

What’s the current (serving) tool used for the docs? mdbook?

6

nix: docbook
nix unstable: mdbook
nixpkgs: docbook (more and more pages are translated with pandoc: CommonMark → pandoc → docbook)
nixos: docbook

I am working on a tool similar to mdbook called mmdoc which is meant to be really fast, and have a very low closure size:

https://github.com/NixOS/nixpkgs/pull/108063

4 Likes
7

Thanks!

With what concrete command a translation from docbook to CommonMark was usually initiated?

Was there even a sort of receipe?

There are remaining xml resources, who somebody might just want to start translating.

8

https://github.com/NixOS/nixpkgs/issues/105758

Is an example with instructions for how to convert a section from Docbook to CommonMark. I haven’t been recommending using a tool to do the conversion since people need to manually change some things anyway.

I’ve been trying to add these instructions to the conversion project for each section so people can do the work in bitesize pieces: