ryantm
October 20, 2020, 11:21am
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
Can’t wait to finally retake my habit of clarifying drive-by contributions.
1 Like
What’s the current (serving) tool used for the docs? mdbook
?
ryantm
April 20, 2021, 8:19pm
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
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.
ryantm
April 21, 2021, 12:05am
8
opened 05:43AM - 03 Dec 20 UTC
closed 02:36PM - 24 Apr 21 UTC
This issue tracks the conversion of `/doc/builders/images/appimagetools.xml` fro… m Docbook to CommonMark per [RFC 72](https://github.com/NixOS/rfcs/blob/master/rfcs/0072-commonmark-docs.md).
If you intend to work on this conversion, please comment below!
# Conversion instructions
1. Comment here that you intend to work on it. (Please also post if you stop working on it.)
2. Checkout a new branch of nixpkgs master.
3. Edit `doc/builders/images.xml`: change `appimagetools.xml` to `appimagetools.section.xml`.
4. Rename `doc/builders/images/appimagetools.xml` to `appimagetools.section.md`.
5. Convert the contents from Docbook to [CommonMark](https://commonmark.org/). Follow [conversion best practices](https://github.com/NixOS/nixpkgs/issues/105243). Use existing `.md` sections for inspiration.
6. Use `nix-build` from the `doc/` folder to build the manual.
7. Preview the manual on your computer at `http://0.0.0.0:8000/manual.html` after running from `doc/` folder:
```
nix-shell -p python3 --run 'python3 -m http.server --directory ./result/share/doc/nixpkgs'
```
8. When it looks good, submit a PR and reference this issue.
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:
https://github.com/NixOS/nixpkgs/projects/37
Let’s give each other the gift of CommonMark this holiday season!
Since RFC 72 has been accepted, we can start converting Nixpkgs and NixOS manuals to CommonMark. The sooner we can get the old docs converted, the sooner we can reap the benefits of better output formats and easier contributions!
To get the ball rolling, I’ve started the
CommonMark Docs project
There’s a bunch of issues in the To Do column that you can help with!
There’s also Docbook to CommonMark Be…