Hi, Stuart Henderson wrote on Sun, Jun 27, 2021 at 08:17:40AM +0100: > On 2021/06/26 22:06, Mike Larkin wrote: >> On Sun, Jun 27, 2021 at 12:40:21PM +1000, Reuben ua Brig wrote:
>>> i would like to prefix this by saying i am writing this as a user >>> giving feedback and not a developing giving patches and anyone who has >>> a problem with that can go shove it rather than telling me to shut up. >>> >>> i noticed for a lot of the ports to openbsd, even in base, a lot of >>> documentation is either missing or, how shall i put it, over-compiled. This remark is amazing. I literally spent years of my life improving that. Please read http://www.openbsd.org/papers/bsdcan18-mandoc.pdf slides 35 to 40. Page 36 documents that i improved what you are asking for by a factor of 180 (it is now one hundred and eighty times better than it used to be). What you are talking about is literally the last 3 permille, the last 30 ports out of 9000. >>> some examples in my memory are: >>> >>> texlive* installs e.g. PDF documenation and removes TeX sources, even >>> though in many cases the TeX sources are an integral part of the >>> documentation. Texlive is *the* ultimate monster port (as far as *individual* ports go; there are no doubt *groups* of ports maintained by individual people or small teams that are even worse, far worse, like GNOME and KDE and mozilla - and OK, admittedly, there are a few other individual monsters, like chrome). I admire Edd for maintaining texlive over all those many years. Nothing about that beast is simple, not even understanding the vast amount of stuff it contains. And yes, texlive documentation is definitely a maze, half a continent of swamps and deserts scattered among jungles of code, containing no end of wild beasts and beautiful gems. Improving that is... some kind of an undertaking, you know. >>> man-pages-posix installs cat files rather than man files. As a matter of fact, it installs *both*. For the 2013-a version, it was forced to do so by this annoying former requirement in the file POSIX-COPYRIGHT: [...] Redistribution of this material is permitted so long as this notice and the corresponding notices within each POSIX manual page are retained on any distribution, *and the nroff source is included*. [...] (my emphasis) In the 2017-a version, that requirement was removed, which jasper@ apparently missed when updating the port last November. I guess i should send a patch to no longer install the source tarball. >>> (b.t.w. the man tools do work with section 0, you just need change >>> the file extension: i would suggest .3p for compatibility with >>> current section.) That's a non-issue as long as mandoc cannot handle the POSIX manuals at all. Besides, 3p is Perl in OpenBSD, so that would a bad choice. >>> anyway i think users would benefit from including more documentation >>> when it is in the sources, You don't say? :-) By the way, it's not just mandoc. For example: https://undeadly.org/cgi?action=article&sid=20190419101505 In particular, after reading the piece, look at the last use case at the very bottom. "The /usr/xenocara/ tree contains about 250 DocBook files. Some of them might contain information worth extracting. I plan to look into that together with matthieu@." After that, look at stuff like man fonts man XKB-Config man XKB-Enhancing man shapelib man synclib man xtest1 man Xmu man drmAvailable man drmHandleEvent man drmModeGetResources man 7 drm man drm-kms man drm-memory man xtrans That's all documentation that was made available in manual page form not too long ago, exactly as you are asking for. Admittedly, the effort stalled somewhat. The task here is extracting the gems from the swamp. Not all of these 250 documents are likely to really benefit users, and we don't want to promote crap. >>> but, you know, its your time, so dont do it >>> if you dont want, just dont be prissy about it. >> your diff to implement what you are asking for is welcome! > Maybe not for man-pages-posix, Right, Stuart, thank you for clarifying that. Improving mandoc(1) such that it becomes able to handle man-pages-posix is among the hardest remaining tasks to solve in mandoc. You are welcome to help improve mandoc if you want to, but you are definitly not welcome to try to make mandoc work with man-pages-posix. Even if you manage to, the diff will be so large, complicated, and intrusive that i won't have the time to review it properly. Here is the mandoc TODO lists: https://cvsweb.bsd.lv/~checkout~/mandoc/TODO?rev=HEAD As a beginner, look for entries that say "loc * exist * algo * size *". But be aware that even those aren't trivial and most of them pose traps for the unwary. If something is really easy, most of the time, it doesn't make it into the file at all but tends to gets fixed on the spot. My rating for making man-pages-posix work is "loc *** exist ** algo *** size **", i.e. it's a cross-module issue involving highly complex algorithms in code of significant difficulty, requiring significant amounts of difficult new code. > it looks like embedded tbl(7) support is needed. mandoc doesn't do this, That's not entirely accurate. Mandoc does have embedded tbl(7) support - as in "tbl(7) code embedded in man(7) or mdoc(7) code". The problem here is that these pages embed non-trivial low-level roff(7) requests as well as man(7) macros *inside* tbl(7) code embedded in an man(7) file (*double* embedding). Mandoc cannot handle requests and macros inside tables, and that's *very* tough to implement. I have a private file containing details about all the ports that still USE_GROFF, and here is the man-pages-posix entry: tbl(7) issues ------------- (XXX These need more detailed classification and description.) [...] books/man-pages-posix * .nf in tbl -- actually needed for poor man's rows man3/complex.h.3:196:2: UNSUPP: ignoring macro in table: nf man3/tgmath.h.3:144:2: UNSUPP: ignoring macro in table: nf man3/gai_strerror.3:39:2: UNSUPP: ignoring macro in table: nf man3/wctype.3:49:2: UNSUPP: ignoring macro in table: nf man1/awk.1:1182:2: UNSUPP: ignoring macro in table: IR man1/bc.1:360:2: UNSUPP: ignoring macro in table: nf * .IR in tbl -- mildly needed for spacing man1/chmod.1:525:2: UNSUPP: ignoring macro in table: IR man1/lex.1:664:2: UNSUPP: ignoring macro in table: BR * .IR in tbl -- mildly needed for markup man1/pax.1:471:2: UNSUPP: ignoring macro in table: IR * unimportant: man3/langinfo.h.3:112:2: UNSUPP: ignoring macro in table: BR man3/signal.h.3:197:4: UNSUPP: ignoring macro in table: sp man3/endutxent.3:126:2: UNSUPP: ignoring macro in table: IR man3/posix_trace_close.3:65:2: UNSUPP: ignoring macro in table: nf man3/regcomp.3:68:2: UNSUPP: ignoring macro in table: IR man3/sigaction.3:54:4: UNSUPP: ignoring macro in table: br man1/c99.1:572:2: UNSUPP: ignoring macro in table: nf man1/expr.1:116:2: UNSUPP: ignoring macro in table: IR man1/file.1:240:2: UNSUPP: ignoring macro in table: P man1/get.1:626:5: UNSUPP: ignoring macro in table: sp man1/ps.1:244:2: UNSUPP: ignoring macro in table: BR man1/yacc.1:1237:2: UNSUPP: ignoring macro in table: IR * whitespace in eqn(7) output: man3/float.h.3 man3/math.h.3 man3/drand48.3 man3/erf.3 man3/lgamma.3 It's the last entry at the bottom because it may be the hardest port to fix... > so they still need to be formatted with groff. Exactly. Reuben, if you don't see that mandoc output is broken for these pages, you need to look harder. Yours, Ingo
