Convert dockertools from Docbook to CommonMark

[ryantm]

This issue tracks the conversion of /doc/builders/images/dockertools.xml from Docbook to CommonMark per RFC 72.

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 dockertools.xml to dockertools.section.xml.
4. Rename doc/builders/images/dockertools.xml to dockertools.section.md.
5. Convert the contents from Docbook to CommonMark. Follow conversion best practices. 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.

[bryanasdev000]

Hi @ryantm, I'd like to work in this issue. First one with documentation so I will probably need to understand a few things first.

[ryantm]

@bryanasdev000 Thanks, let us know if you need help!

[roberth]

Hi @bryanasdev000, thanks for picking this up. Are you still working on this? If you're stuck, you could create a draft PR so someone can help, or if you've changed your mind that's also ok.

[bryanasdev000]

Hi @bryanasdev000, thanks for picking this up. Are you still working on this? If you're stuck, you could create a draft PR so someone can help, or if you've changed your mind that's also ok.

Hi @roberth! Sorry for late reply.

I worked a little bit, on and off during the holidays, I do not finished yet, I had some problems during the build of the documentation, but from what I read (pandoc output) I made some mistakes during the file conversion.

For now, I didn't commit, It's on my personal computer only.

As the week is a little difficult, I'll see if I finish it at the weekend.

(Maybe I should have asked for this issue just now, just see 14 days ago and I was like "What ?! That was 2 weeks ago ?!" LOL)

Thanks for asking!

[bryanasdev000]

Hi @bryanasdev000, thanks for picking this up. Are you still working on this? If you're stuck, you could create a draft PR so someone can help, or if you've changed your mind that's also ok.

Hi @roberth, I followed your suggestion to create a draft PR, at the moment I'm stuck in two things, the first is how to create a note and the second reference errors during the build of the documentation.

For the first, pandoc created notes with the following formats: ::: {.note} Using this parameter requires the kvm device to be available. :::, in this case I should use the default way to create notes in markdown (using > **_NOTE:_**) or wrap this in docbook way?

If I remove the references that generate the error below, I can verify that using the markdown format, this note is styled differently from the rest of the documentation.

And for the build errors, here is log:

...
warning: failed to load external entity "functions/library/generated/overrides/lib.options.showOption.xml"
jing doc-support/result/docbook.rng manual-full.xml
/build/doc/manual-full.xml:13148:59: error: IDREF "ex-dockerTools-buildImage-runAsRoot" without matching ID
/build/doc/manual-full.xml:12728:49: error: IDREF "ex-dockerTools-buildImage" without matching ID
make: *** [Makefile:29: validate] Error 1
builder for '/nix/store/yajds5xax6hjdjdqm4y23xvkvhpbr36r-nixpkgs-manual.drv' failed with exit code 2
error: build of '/nix/store/yajds5xax6hjdjdqm4y23xvkvhpbr36r-nixpkgs-manual.drv' failed

For this I tried (see <xref linkend="ex-dockerTools-buildImage"/>) per #105243 but build fails with same error.

Any help is appreciated.