@tazjin I think I remember at least one person asking for an epub version before…! Though I’m not really sure what you’re supposed to do with that, the NixOS manual is really not meant to be a book or to be read as one. Never heard of anybody wanting the PDF. I feel like those formats might just have been added because they’re well supported by Docbook.
I’m using nixpkgs.go-md2man on the direnv project to convert Markdown to man pages. The ROFF format is very limited so I had to edit the Markdown quite a bit until it gives out a nice result.
I prefer PDFs for reading on an iPad, which means when I’m going to dig into something new and I’m not scanning for the answer to a precise question. Or when reading academic papers. Even though I like reading on the iPad, I avoid epub for technical things because it will sometimes mess up formatting, wrapping code and squishing sidebars.
Continuing the effort, here is a PR to reuse options generation outside nixos: Extract NixOS options documentation generation to a function by domenkozar · Pull Request #66328 · NixOS/nixpkgs · GitHub
1 Like
@tazjin this is why I dislike Markdown. List formatting is 
. Code block is not indented, list numbers are not computed automatically. How does Google solve this kind of problems?
Where’s this from? Looks like the source Markdown is incorrect. Tried to search for an exact quote from that, but no results.
We have code reviews, auto-formatting & linting for Markdown - same as other languages.
Demo.
Markdown - asciidoc.adoc · GitHub
Asciidoc - asciidoc.adoc · GitHub
Asciidoc is just superior over markdown in list formatting.
The comparison is a bit disingenuous. Here’s the disingenuousness flipped:
I removed the + from asciidoc (used to implement complex content), and added the proper indentation with spaces for markdown (used to implement complex content).
3 Likes
I’d really like to see NixOS documentaition done with Sphinx. I have some years of experience with it, including writing small extensions for it and I could help converting docs to RestructuredText / Sphinx. ReST is better for documentation but Sphinx also supports Markdown so parts could be written in Markdown and converted later if there’s a need for it. Readthedocs is based on Sphinx and it’s used for many projects, including the Linux kernel and Python. Here’s the story for the Linux kernel:
Asciidoc is mentioned here and in the article but I don’t have experience with Asciidoc and the tooling for it. How does it compare to Sphinx and why could it be a better choice?
I didn’t know that sphinx can use Markdown as a source, anyway I stopped converting docbook for a number of reasons:
- there are many writing styles inside the documentation, so more than a way to reach the same result in html formatting using docbook, and a converter must take that into account;
- sphinx (at least the last time I checked) doesn’t have yet support for the annotated source examples, a thing that I think asciidoc has instead;
- creating new domais (for example I thought of creating a Nix domain) as of one year ago was completely undocumented.
Anyway, if you are at the nixconf I can show you something. If you aren’t, I’ll try to cook up something (if it still works out of the box after more than an year)
I’m at Nixcon today (front row on the right side for the current talk). @asymmetric and @domenkozar want to talk about docs tomorrow but I don’t have a ticket for the Hackday.
1 Like
I’m currently on the one of the last rows on the left, on the first seat from right, checkout my avatar image 
Ok, I will be at the Hackday so we can talk about docs 
2 Likes
Do we have the video of yesterday’s @grahamc presentations somewhere? maybe it would be nice to have a transcript of some part of it to use as starting point for a beginner’s doc…
The videos are available on the NixCon YouTube channel. I think they’ll be a great resource in the future.
2 Likes
Oh, I didn’t have anything to do with producing these videos. I just happened to find them on youtube 
I’d really like to see NixOS documentaition done with Sphinx. I have some years of experience with it, including writing small extensions for it and I could help converting docs to RestructuredText / Sphinx. ReST is better for documentation but Sphinx also supports Markdown so parts could be written in Markdown and converted later if there’s a need for it. Readthedocs is based on Sphinx and it’s used for many projects, including the Linux kernel and Python. Here’s the story for the Linux kernel:
But we can also use Markdown in the nix configuration, you have to
https://github.com/NixOS/nixpkgs/blob/b27bdf4ec8a02c1c956b15c344069f492b4babc6/doc/Makefile#L89 sections
and chapters.
Asciidoc is mentioned here and in the article but I don’t have experience with Asciidoc and the tooling for it. How does it compare to Sphinx and why could it be a better choice?
I have experiance with asciidoc, and they are not good.
For example asciidoc is only an output format for pandoc. I also
couldn’t find a tool to write asciidoc with prerendering. I thought, back
than, that pull requests get easier to review, but I doubt there will be
an improvment compared to docbook.
I have no idea about Sphinx, but the possibility to use markdown is
already there.