Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

manual page consistency #273

Open
dylanaraps opened this issue Jul 9, 2021 · 7 comments
Open

manual page consistency #273

dylanaraps opened this issue Jul 9, 2021 · 7 comments
Labels
future not now

Comments

@dylanaraps
Copy link
Member

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.
  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 dylanaraps added the future not now label Jul 9, 2021
@dylanaraps
Copy link
Member Author

dylanaraps commented Jul 11, 2021

Packages with documentation issues in core:

  • busybox (has no manuals) (man-pages-posix (at least for partial coverage?))
  • grub (requires help2man).
  • 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?)
  • mpv (html only?)
  • 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)
  • 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
Copy link

aabacchus commented Jul 11, 2021

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 added a commit that referenced this issue Jul 12, 2021
dylanaraps added a commit that referenced this issue Jul 12, 2021
dylanaraps added a commit that referenced this issue Jul 12, 2021
dylanaraps added a commit that referenced this issue Jul 12, 2021
dylanaraps added a commit that referenced this issue Jul 12, 2021
@dylanaraps
Copy link
Member Author

dylanaraps commented Jul 12, 2021

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

dylanaraps added a commit that referenced this issue Jul 12, 2021
We need man-pages-posix to fill in the gaps where man-pages
provides glibc related information.

This also renames the directories from man[013]p to man[013]
to avoid having to use makewhatis + the mandoc database.
dylanaraps added a commit that referenced this issue Jul 12, 2021
NOTE: They're only kept if scdoc is installed. This is the first
step towards a more complete solution.
dylanaraps added a commit that referenced this issue Jul 12, 2021
NOTE: They're only kept if scdoc is installed. This is the first
step towards a more complete solution.
@dilyn-corner
Copy link

dilyn-corner commented Jul 12, 2021

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
Copy link

jedahan commented Jul 14, 2021

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
Copy link

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

@aabacchus
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
future not now
Development

No branches or pull requests

4 participants