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! 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…