4 ms·
They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentatio
by Sanddancer 10y ago
They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k <thing> is a lot easier to remember than some other search tool that requires its own set of packages, etc.
- Jtsummers 10y agoNothing prevents their new solution from generating man pages as a way to create end user accessible documents.
- grive 10y agoManpages are not a format to write the documentation, but to display it. You can `make mandocs` in the linux tree, then `make installmandocs` to make them easily accessible with the man command, i.e. `man struct_sk_buff` will display the definition of an sk_buff.
- dend 10y agoThe problem with that approach is that you are limiting yourself to fundamentally primitive documentation (and by primitive I mean non-interactive). Granted, for a kernel it might be less important, but it's great when there is a good architecture diagram/image instead of 7 paragraphs.
- Sanddancer 10y agoManpages can have a rather large amount of interactivity. Documents can be formatted as text, as HTML, with links, etc. The problem is that manpages are an afterthought in too much of the Linux ecosystem, so people have low expectations and low beliefs in what they can actually do. They can have tables, they can have equations, they can have graphics.
- bduhan 10y agoYou can build man pages with Sphinx. http://www.sphinx-doc.org/en/stable/builders.html http://www.sphinx-doc.org/en/stable/builders.html
- dozzie 10y agoHave you actually tried to use this for something real? Sphinx source doesn't seem suited for man pages at all, and formatting seems the least important bit that doesn't fit.