manual page consistency

[dylanaraps]

Packages should be consistent regarding their manual pages. Right now, things are a little messy. Some packages provide them in generated form while others require specific tooling for generation. In the latter case we pretend the manuals do not exist. For some libraries with many manual pages (open/libressl, etc), we currently disable them. There's no consistency in other words.

The ideal situation is as follows:

1. All packages provide manual pages.
2. Users can choose whether or not to install manual pages via KISS_HOOK.
   • Availability of this option should be made as obvious as possible.
   • See: https://kisslinux.xyz/package-manager#6.2
3. No extra dependencies when user chooses not to install manual pages.

This is going to be handled on a per-package basis. Packages with "free" manual pages will swap to simply providing them. Packages which require specific generation tools will be evaluated one by one. A list of every generation tool will then be compiled and we can move forwards from there. In the absolute worst case (where it isn't feasible to package a generation tool), we can provide our own generated manual pages for packages which require them.

The trickiness comes into play with 3) and dependency resolution. I'm sure the solution will present itself. This is marked future. Posting here to start the discussion.

[dylanaraps]

Packages with documentation issues in core:

• [x] busybox (has no manuals) (man-pages-posix (at least for partial coverage?))
• [x] grub (requires help2man).
• [x] musl (provided by man-pages-posix/man-pages (though these packages need filtering)).
• [ ] ~~xz (has man1, man3 needs doxygen).~~
• [ ] kiss (need to create a manual!)

~~help2man is written in perl so we need to write our own implementation.~~ Done

Packages with documentation issues in extra:

• [ ] alsa-lib (has no manuals).
• [ ] atk (gtk-doc)
• [ ] cairo (gtk-doc)
• [ ] cbindgen (just has a single markdown file)
• [ ] ccache (asciidoc, html only(?))
• [ ] clang (libxml2(?), html only(?))
• [ ] cmake (html only(?))
• [ ] expat (docbook (needs conversion from xml to man))
• [ ] fontconfig (docbook (needs conversion from xml to man))
• [ ] freetype (html only(?))
• [ ] harfbuzz (html only(?))
• [ ] gdk-pixbuf (gtk-doc)
• [ ] glib (gtk-doc(?))
• [ ] gtk+3 (gtk-doc)
• [ ] intel-vaapi-driver (no manuals?)
• [ ] ~~json-c (doxygen (html only?))~~
• [ ] ~~lame (no library manuals?)~~
• [ ] libass (no manuals?)
• [ ] ~~libjpeg-turbo (doxygen)~~
• [ ] libogg (html only)
• [ ] libtheora (html only)
• [ ] libudev-zero (grab upstream manuals?)
• [ ] ~~libva (doxygen)~~
• [ ] libva-utils (no manuals?)
• [ ] libvorbis (latex + html?)
• [ ] ~~libvpx (doxygen)~~
• [ ] ~~libwebp (no library manuals)~~
• [ ] llvm (libxml2(?), html only(?))
• [ ] mesa (opengl-man-pages?)
• [x] mpv (html only?)
• [x] mutt (perl required?)
• [ ] ~~opus (doxygen)~~
• [ ] pango (gtk-doc)
• [ ] sqlite (sqlite3-doc package)
• [ ] util-linux (asciidoctor)
• [ ] x264 (just some txt files with bad line wrapping)
• [ ] x265 (no manuals in sources, just website links)
• [ ] xvidcore (no manuals)
• [ ] ~~zstd (library has no manuals, just html)~~

Packages with documentation issues in wayland.

• [ ] foot / foot-pgo (scdoc)
• [ ] grim (scdoc)
• [x] libdrm (rst2man)
• [ ] libinput (sphinx)
• [ ] libpciaccesas (no manuals?)
• [ ] libseat (scdoc)
• [ ] ~~libxkbcommon (doxygen)~~
• [ ] pixman (no manuals)
• [ ] slurp (scdoc)
• [ ] sway / sway-no-seat / sway-tiny (scdoc)
• [ ] ~~wayland (doxygen)~~
• [ ] wbg (no manuals)
• [ ] wlroots (scdoc)
• [ ] wlsunset (scdoc)

[aabacchus]

busybox does have a man page, but it's simply all the --help messages for each applet listed. certainly most of the core utilities have dedicated man-pages-posix, and only the ~interesting~ applets (httpd, sendmail, etc) don't have any decent, busybox-specific manuals.

[dylanaraps]

OK. Every package without manual pages (or with partial manual pages - ie, pages for utilities, none for library)) has been listed above. Now it's just a matter of ticking each little box.

Notes:

• scdoc has been packaged. This is really nice. Build takes one second and the tool clocks in at 80k. I have no qualms about making this a make depend.

• gtk-doc looks awful to package (many dependencies, very complex).

• help2man requires perl but we can write our own implementation.

• asciidoc looks awful to package..

• docbook seems to need some xml schemes and libxml2.

• asciidoctor seems to need ruby(?) though there may be other implementations.

• doxygen ...

• sphinx requires python.

• mesa needs https://github.com/KhronosGroup/OpenGL-Refpages#building

[dilyn-corner]

docbook is unpleasant in general to deal with packaging-wise, and there was a breaking change in their last major version release; you might have to use an older version for some or all packages requiring docbook (for instance, all KDE packages still require docbook 4.x afaik; I have no idea about any of these, ofc).

It was previousl packaged in KISS-kde and you can take a look at that if you'd like. I have no clue if it actually worked or not; I've always deleted docs from my packages and never bothered to investigate. https://github.com/dilyn-corner/KISS-kde/tree/5f5a92a1e18b5eb4f8e108bfd32281aecaadda29/extra

[jedahan]

I have docbook-xsl packaged if thats at all helpful https://github.com/jedahan/kiss-repo/tree/main/docbook-xsl . I think it was a prerequisite for docbook-xml, which i am having trouble finding. must be in a repo that went away.

[aabacchus]

The xkeyboard-config package does not currently provide any documentation, although it exists: https://linux.die.net/man/7/xkeyboard-config.

[aabacchus]

Re: docbook, I just came across this utility from the excellent bsd.lv collection: https://mandoc.bsd.lv/docbook2mdoc/

The docbook2mdoc utility is a converter from DocBook version 4.x and 5.x XML to mdoc. Unlike most DocBook utilities, it's a standalone ISC-licensed ISO C utility with no external dependencies that should compile on any modern UNIX system.