* All caps .TH page name @ 2022-07-21 14:29 Alejandro Colomar 2022-07-21 18:36 ` G. Branden Robinson 0 siblings, 1 reply; 27+ messages in thread From: Alejandro Colomar @ 2022-07-21 14:29 UTC (permalink / raw) To: Ingo Schwarze, G . Branden Robinson; +Cc: linux-man [-- Attachment #1.1: Type: text/plain, Size: 987 bytes --] Hi Branden and Ingo! I've never been convinced about the page title being in all caps in the .TH line. From recent groff@ discussions, I guess that neither of you are either. I'd like to know why this has been the case historically, and any opinions you might have about me changing the man-pages to use the same caps as the actual identifier that I'm documenting (most of the time that would mean lowercase). Basically, the same rules as within .SH NAME. Also, does it have any functional implications? I'm especially interested in knowing if that may affect in any way the ability of man(1) to find a page when invoked as `man TIMESPEC` for example. I'm not saying necessarily that I'd like to keep that behavior. I wouldn't mind breaking it, if it means that users will be able to differentiate upper- and lowercase pages. We're not in Windows (nor MacOS), anyway. Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page name 2022-07-21 14:29 All caps .TH page name Alejandro Colomar @ 2022-07-21 18:36 ` G. Branden Robinson 2022-07-21 23:16 ` All caps .TH page title Alejandro Colomar 2022-07-22 16:19 ` All caps .TH page name Ingo Schwarze 0 siblings, 2 replies; 27+ messages in thread From: G. Branden Robinson @ 2022-07-21 18:36 UTC (permalink / raw) To: Alejandro Colomar; +Cc: Ingo Schwarze, linux-man [-- Attachment #1: Type: text/plain, Size: 2697 bytes --] Hi Alex, At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote: > I've never been convinced about the page title being in all caps in > the .TH line. From recent groff@ discussions, I guess that neither of > you are either. Well, Ingo was more comfortable with it than I was. > I'd like to know why this has been the case historically, and any > opinions you might have about me changing the man-pages to use the > same caps as the actual identifier that I'm documenting (most of the > time that would mean lowercase). Basically, the same rules as within > .SH NAME. I've read every edition of the Unix manual from Version 1 (1971) to Version 7 (1979) and my surmise is that it was sheer inertia. The Teletype machines that were used to set the original versions of the manual--remember, this is before troff even existed--might have been capable of boldface through overstriking, but was not used this way as far as I can tell in the V1 through V3 manual. So this means that, for emphasis, you had regular type and underlined type and that was it. Under such limitations, the use of full capitals for emphasis is not surprising. After that--the V4 manual was the first to be typeset with troff--the practice of full-capping the page titles in the headers was retained. How deliberate a choice this was is not something I can answer. The decision was made in 1972. You could ask some of the surviving principal Bell Labs CSRC figures on the TUHS mailing list. > Also, does it have any functional implications? I'm especially > interested in knowing if that may affect in any way the ability of > man(1) to find a page when invoked as `man TIMESPEC` for example. My understanding is that mandb(8) indexes based solely on the second argument to the `TH` macro call and (what it interprets as) the contents of the "Name" (or "NAME") section of the page. It parses *roff itself as best it can to determine this. So the fact that the _first_ argument to `TH` might be in full caps doesn't deter it. (It might in fact have made mandb(8) authors' job easier if an "honest lettercase" practice had arisen back in the day--but it didn't). Since he's a mandb(8) author/maintainer, I would again defer to Colin Watson's knowledge and expertise in this area. > I'm not saying necessarily that I'd like to keep that behavior. I > wouldn't mind breaking it, if it means that users will be able to > differentiate upper- and lowercase pages. We're not in Windows (nor > MacOS), anyway. True, although I would take a jaundiced view toward any software project that distinguished its man page names, whether internally or from others' solely by a difference in lettercase. Regards, Branden [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-21 18:36 ` G. Branden Robinson @ 2022-07-21 23:16 ` Alejandro Colomar 2022-07-22 0:22 ` Colin Watson 2022-07-22 2:14 ` G. Branden Robinson 2022-07-22 16:19 ` All caps .TH page name Ingo Schwarze 1 sibling, 2 replies; 27+ messages in thread From: Alejandro Colomar @ 2022-07-21 23:16 UTC (permalink / raw) To: G. Branden Robinson; +Cc: Ingo Schwarze, linux-man, Colin Watson, groff [-- Attachment #1.1: Type: text/plain, Size: 4527 bytes --] Hi Branden, On 7/21/22 20:36, G. Branden Robinson wrote: > Hi Alex, > > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote: >> I've never been convinced about the page title being in all caps in >> the .TH line. From recent groff@ discussions, I guess that neither of >> you are either. > > Well, Ingo was more comfortable with it than I was. > >> I'd like to know why this has been the case historically, and any >> opinions you might have about me changing the man-pages to use the >> same caps as the actual identifier that I'm documenting (most of the >> time that would mean lowercase). Basically, the same rules as within >> .SH NAME. > > I've read every edition of the Unix manual from Version 1 (1971) to > Version 7 (1979) and my surmise is that it was sheer inertia. The > Teletype machines that were used to set the original versions of the > manual--remember, this is before troff even existed--might have been > capable of boldface through overstriking, but was not used this way as > far as I can tell in the V1 through V3 manual. > > So this means that, for emphasis, you had regular type and underlined > type and that was it. > > Under such limitations, the use of full capitals for emphasis is not > surprising. That makes sense. > > After that--the V4 manual was the first to be typeset with troff--the > practice of full-capping the page titles in the headers was retained. > > How deliberate a choice this was is not something I can answer. The > decision was made in 1972. You could ask some of the surviving > principal Bell Labs CSRC figures on the TUHS mailing list. Is Doug one of them? I've seem him on the groff@ list from time to time. I added the groff@ list, in case this is of interest to someone there. > >> Also, does it have any functional implications? I'm especially >> interested in knowing if that may affect in any way the ability of >> man(1) to find a page when invoked as `man TIMESPEC` for example. > > My understanding is that mandb(8) indexes based solely on the second > argument to the `TH` macro call and (what it interprets as) the contents > of the "Name" (or "NAME") section of the page. It parses *roff itself > as best it can to determine this. So the fact that the _first_ argument > to `TH` might be in full caps doesn't deter it. (It might in fact have > made mandb(8) authors' job easier if an "honest lettercase" practice had > arisen back in the day--but it didn't). Okay. > > Since he's a mandb(8) author/maintainer, I would again defer to Colin > Watson's knowledge and expertise in this area. Added to CC, in case he wants to intervene. > >> I'm not saying necessarily that I'd like to keep that behavior. I >> wouldn't mind breaking it, if it means that users will be able to >> differentiate upper- and lowercase pages. We're not in Windows (nor >> MacOS), anyway. > > True, although I would take a jaundiced view toward any software project > that distinguished its man page names, whether internally or from > others' solely by a difference in lettercase. Heh! You've never tried to clone the Linux man-pages in Windows or MacOS, it seems :p $ find man* -type f \ | tr '[:upper:]' '[:lower:]' \ | sort \ | uniq -d \ | while read f; do find man* -type f \ | grep -i $f; done; man2/_Exit.2 man2/_exit.2 man3/nan.3 man3/NAN.3 $ find man* -type f \ | tr '[:upper:]' '[:lower:]' \ | sort \ | uniq -d \ | while read f; do find man* -type f \ | grep -i $f; done \ | while read f; do echo ===$f===; head -n1 $f; done; ===man2/_Exit.2=== .so man2/_exit.2 ===man2/_exit.2=== .\" This manpage is Copyright (C) 1992 Drew Eckhardt; ===man3/nan.3=== .\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) ===man3/NAN.3=== .so man3/INFINITY.3 At least, _Exit(2) and _exit(2) point to the same page. nan(3) and NAN(3) don't, though! We can't blame the writers, since the identifiers have those names in C. Luckily, man(1) shows you the right page if you specify the right string. I feel a need to fix this lack of precision in the page titles. Unless someone opposes to it with some strong reason, which I don't expect. It'll take some time to do it, but if no-one speaks in a reasonable time, I'll start doing it :). Cheers, Alex > > Regards, > Branden -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-21 23:16 ` All caps .TH page title Alejandro Colomar @ 2022-07-22 0:22 ` Colin Watson 2022-07-22 1:34 ` G. Branden Robinson 2022-07-22 14:44 ` Ingo Schwarze 2022-07-22 2:14 ` G. Branden Robinson 1 sibling, 2 replies; 27+ messages in thread From: Colin Watson @ 2022-07-22 0:22 UTC (permalink / raw) To: Alejandro Colomar; +Cc: G. Branden Robinson, Ingo Schwarze, linux-man, groff On Fri, Jul 22, 2022 at 01:16:49AM +0200, Alejandro Colomar wrote: > On 7/21/22 20:36, G. Branden Robinson wrote: > > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote: > > > Also, does it have any functional implications? I'm especially > > > interested in knowing if that may affect in any way the ability of > > > man(1) to find a page when invoked as `man TIMESPEC` for example. > > > > My understanding is that mandb(8) indexes based solely on the second > > argument to the `TH` macro call and (what it interprets as) the contents > > of the "Name" (or "NAME") section of the page. It parses *roff itself > > as best it can to determine this. So the fact that the _first_ argument > > to `TH` might be in full caps doesn't deter it. (It might in fact have > > made mandb(8) authors' job easier if an "honest lettercase" practice had > > arisen back in the day--but it didn't). > > Okay. > > > Since he's a mandb(8) author/maintainer, I would again defer to Colin > > Watson's knowledge and expertise in this area. > > Added to CC, in case he wants to intervene. The above is not quite correct. man-db doesn't index on the .TH section at all, and I don't believe I've encountered the practice of doing so in other indexers (I could be wrong, but I think that's something I would have remembered if I'd noticed it). Rather, it parses the "NAME" (or "Name", or a number of localized variants) section of pages using the man macro set for "foo \- description" lines and uses the left-hand side of those for page names, or equivalently looks for .Nm requests in pages using the mdoc macro set. With the exception of handling localized variants of that section name, which is a pretty ugly pile of special cases, I believe this to be fairly traditional behaviour. I can't say I would have done it that way if I'd been designing the system from scratch since it really involves far too much half-arsed parsing, but it seemed to be the usual thing to do when I came on the scene. Changing the arguments to .TH won't bother man-db at all. > > > I'm not saying necessarily that I'd like to keep that behavior. I > > > wouldn't mind breaking it, if it means that users will be able to > > > differentiate upper- and lowercase pages. We're not in Windows (nor > > > MacOS), anyway. man-db's man(1) performs case-insensitive lookups by default, which I've found to be more useful behaviour. Case-sensitive lookup can be requested using the -I/--match-case option. As far as I know this was an innovation when I introduced it in 2002, so I don't know how widespread this behaviour is among man(1) implementations. You probably can't rely on it. But in any case, as above, changing the arguments to .TH doesn't affect this. I haven't noticed it being widespread practice to spuriously capitalize the name part of lines in the "NAME" section. Cheers, -- Colin Watson (he/him) [cjwatson@debian.org] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 0:22 ` Colin Watson @ 2022-07-22 1:34 ` G. Branden Robinson 2022-07-22 4:07 ` G. Branden Robinson 2022-07-22 14:44 ` Ingo Schwarze 1 sibling, 1 reply; 27+ messages in thread From: G. Branden Robinson @ 2022-07-22 1:34 UTC (permalink / raw) To: Alejandro Colomar, Ingo Schwarze, linux-man, groff [-- Attachment #1: Type: text/plain, Size: 4061 bytes --] At 2022-07-22T01:22:57+0100, Colin Watson wrote: > On Fri, Jul 22, 2022 at 01:16:49AM +0200, Alejandro Colomar wrote: > > On 7/21/22 20:36, G. Branden Robinson wrote: > > > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote: > > > > Also, does it have any functional implications? I'm especially > > > > interested in knowing if that may affect in any way the ability > > > > of man(1) to find a page when invoked as `man TIMESPEC` for > > > > example. > > > > > > My understanding is that mandb(8) indexes based solely on the > > > second argument to the `TH` macro call and (what it interprets as) > > > the contents of the "Name" (or "NAME") section of the page. It > > > parses *roff itself as best it can to determine this. So the fact > > > that the _first_ argument to `TH` might be in full caps doesn't > > > deter it. (It might in fact have made mandb(8) authors' job > > > easier if an "honest lettercase" practice had arisen back in the > > > day--but it didn't). [...] > > > Since he's a mandb(8) author/maintainer, I would again defer to > > > Colin Watson's knowledge and expertise in this area. [...] > > The above is not quite correct. man-db doesn't index on the .TH > section at all, and I don't believe I've encountered the practice of > doing so in other indexers (I could be wrong, but I think that's > something I would have remembered if I'd noticed it). Rather, it > parses the "NAME" (or "Name", or a number of localized variants) > section of pages using the man macro set for "foo \- description" > lines and uses the left-hand side of those for page names, or > equivalently looks for .Nm requests in pages using the mdoc macro set. Ah, thanks, Colin. A quick consultation of ncurses man pages reveals that mandb(8)'s idea of the manual section comes from its place in the directory hierarchy, not from parsing the arguments to the `TH` call. My error! > With the exception of handling localized variants of that section > name, which is a pretty ugly pile of special cases, I believe this to > be fairly traditional behaviour. I can't say I would have done it > that way if I'd been designing the system from scratch since it really > involves far too much half-arsed parsing, but it seemed to be the > usual thing to do when I came on the scene. We could have groff man(7) and mdoc(7) recognize a register, named `INDEX`, `DB`, or `SUMMARIZE` or something, which would cause the package(s) to emit the required information, derived solely from page content, in a desirable format. Say, JSON, maybe. Upon seeing this register and reporting the data, the package could then invoke `nx` to move to the next input file. Thus, potentially, the indexing data could be generated with great speed--you could call groff (or nroff, it wouldn't matter) with as many man page file arguments as desired, specifying no preprocessor options (except maybe those for preconv), and a large percentage of page content would never even be read, let alone formatted. Why, I wonder, was the thing not done this way in the first place? Possibly because what follows "Name" can be arbitrary roff language input. However... The "Name" section's contents can be stored in a diversion. In normal circumstances, this diversion's contents would be emitted immediately upon any other `SH` call (or, for degenerate pages that declare no sections after "Name", when the page's end macro is called[1]). Once in a diversion, these contents are subject to "sanitization", a feature I'm chewing over adding to the formatter.[2] The gist is that all the garbage (font changes, special character escape sequences) you currently spent time parsing or stripping away is already removed or transformed for you, leaving clean, printable ASCII or UTF-8. At this point I pause to let the wave of horror break over my audience. Regards, Branden [1] andoc.tmac contrives for this to be the case when rendering multiple pages. [2] https://savannah.gnu.org/bugs/?62787 [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 1:34 ` G. Branden Robinson @ 2022-07-22 4:07 ` G. Branden Robinson 0 siblings, 0 replies; 27+ messages in thread From: G. Branden Robinson @ 2022-07-22 4:07 UTC (permalink / raw) To: Alejandro Colomar, Ingo Schwarze, linux-man, groff [-- Attachment #1: Type: text/plain, Size: 572 bytes --] At 2022-07-21T20:34:39-0500, G. Branden Robinson wrote: > Ah, thanks, Colin. A quick consultation of ncurses man pages reveals > that mandb(8)'s idea of the manual section comes from its place in the > directory hierarchy, not from parsing the arguments to the `TH` call. > My error! Sorry, no, I was still wrong. I guess it comes from the file extension on the man page. John Gardner's not the only person having trouble today. 90 dB of fans and a dehumidifier to dry out a flooded floor does not make for the most productive thinking environment. Regards, Branden [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 0:22 ` Colin Watson 2022-07-22 1:34 ` G. Branden Robinson @ 2022-07-22 14:44 ` Ingo Schwarze 1 sibling, 0 replies; 27+ messages in thread From: Ingo Schwarze @ 2022-07-22 14:44 UTC (permalink / raw) To: Colin Watson, Alejandro Colomar, g.branden.robinson; +Cc: linux-man, groff Hi, Colin Watson wrote on Fri, Jul 22, 2022 at 01:22:57AM +0100: > man-db doesn't index on the .TH section at all, and I don't believe > I've encountered the practice of doing so in other indexers > (I could be wrong, but I think that's something I would have > remembered if I'd noticed it). FWIW, the mandoc(1) implementation of the indexes uses the following to derive names for a page: * the first component of the file name, including of hard, soft, and .so links * in man(7) pages, the first argument of the .TH macro <<===== * in man(7) pages, any words preceding the first "-" or "\-" in the NAME section * in mdoc(7) pages, the first argument of the .Dt macro <<===== * in mdoc(7) pages, arguments of .Nm macros in the NAME section * in mdoc(7) pages, arguments of .Nm macros in the SYNOPSIS * in mdoc(7) pages, first arguments of .Fo and .Fn macros in the SYNOPSIS The last two - mdoc(7) SYNOPSIS content - are only used for man -k searches explicitly specifying the Nm search key. All others are also used for plain man(1) name lookup. In mandoc the following are used as section names: * if the directory name starts with "man" or "cat", the rest of it * the file name suffix, starting after the last dot * in man(7) pages, the second argument of the .TH macro * in mdoc(7) pages, the second argument of the .Dt macro The above rules often cause pages to end up with more than on name and and more than one section. For example, a file called man3p/strcpy.3 containing .TH strlcat 3bsd .SH NAME wcslcpy, wcslcat \- yadayada can be found with any of the following commands, and several more: man 3bsd strcpy man 3 strlcat man wcslcat man 3p wcslcpy As a special case, if the .TH or .Dt argument agrees with one among the other names but differs in case, it is not used, because mandoc assumes the other name is likely correctly cased while the name in the .TH or .Dt macro may have been converted to all caps. > man-db's man(1) performs case-insensitive lookups by default, which > I've found to be more useful behaviour. Case-sensitive lookup can be > requested using the -I/--match-case option. In the mandoc implementation, plain man(1) follows the tradition of being case-sensitive, but i must admit examples of manual pages with names that differ only in case are hard to find indeed, so it might make sense to change this and make it agree with man-db. In the mandoc implementation of apropos(1), searches use case-insensitive extended regular expressions by default (which originally was a proposal coming from FreeBSD). If the regular expression operator '~' is explicitly specified, the search becomes case-sensitive. If the -i option is given, it becomes case-insensitive again. The substring-search operator '=' always remains case-insensitive no matter what. > As far as I know this was an innovation when I introduced it in 2002, > so I don't know how widespread this behaviour is among man(1) > implementations. You probably can't rely on it. > > But in any case, as above, changing the arguments to .TH doesn't affect > this. I haven't noticed it being widespread practice to spuriously > capitalize the name part of lines in the "NAME" section. Indeed, doing that would be very bad style, not least because it would make the correct capitalization of the name hard to find for the human reader of the manual page. Yours, Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-21 23:16 ` All caps .TH page title Alejandro Colomar 2022-07-22 0:22 ` Colin Watson @ 2022-07-22 2:14 ` G. Branden Robinson 2022-07-22 10:35 ` Alejandro Colomar (man-pages) 1 sibling, 1 reply; 27+ messages in thread From: G. Branden Robinson @ 2022-07-22 2:14 UTC (permalink / raw) To: Alejandro Colomar; +Cc: linux-man, groff [-- Attachment #1: Type: text/plain, Size: 2860 bytes --] [Colin and Ingo dropped from CC since I know they read the groff list] Hi Alex, At 2022-07-22T01:16:49+0200, Alejandro Colomar wrote: > On 7/21/22 20:36, G. Branden Robinson wrote: > > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote: > > > I've never been convinced about the page title being in all caps > > > in the .TH line. [...] > > > I'd like to know why this has been the case historically, and any > > > opinions you might have about me changing the man-pages to use the > > > same caps as the actual identifier that I'm documenting (most of > > > the time that would mean lowercase). Basically, the same rules as > > > within .SH NAME. [...] > > After that--the V4 manual was the first to be typeset with > > troff--the practice of full-capping the page titles in the headers > > was retained. > > > > How deliberate a choice this was is not something I can answer. The > > decision was made in 1972. You could ask some of the surviving > > principal Bell Labs CSRC figures on the TUHS mailing list. > > Is Doug one of them? I've seem him on the groff@ list from time to > time. I added the groff@ list, in case this is of interest to someone > there. Yes, Doug McIlroy follows both the groff and TUHS lists. > Heh! You've never tried to clone the Linux man-pages in Windows or MacOS, > it seems :p No, can't say I've had the...pleasure. > At least, _Exit(2) and _exit(2) point to the same page. nan(3) and > NAN(3) don't, though! Pretty gross. A useful counterexample of good practice, though. > We can't blame the writers, since the identifiers have those names in > C. Luckily, man(1) shows you the right page if you specify the right > string. Yes, and at least they're closely related and from the same project. This is the only man page I know of that documents only simple (i.e., not function-like) C preprocessor macros. You're more conversant with libc-ish man pages so you may know of others, but this is the sort of content that, as a user, I would prefer to find in, say, a "math.h(3)" man page. Having these constants in a page by themselves does little to situate them within the context of the C math library API. But I know I have suggested this to you before. ;-) I observe that the most popular simple macro of all, NULL, has no man page. > I feel a need to fix this lack of precision in the page titles. > Unless someone opposes to it with some strong reason, which I don't > expect. You never know. But keep in mind that a strong objection is not the same thing as a strong reason. > It'll take some time to do it, but if no-one speaks in a reasonable > time, I'll start doing it :). We should all practice our scowling faces for anyone who dares to promulgate man pages named "lS", "prIntf", or similar. Regards, Branden [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 2:14 ` G. Branden Robinson @ 2022-07-22 10:35 ` Alejandro Colomar (man-pages) 2022-07-22 11:46 ` Alejandro Colomar 0 siblings, 1 reply; 27+ messages in thread From: Alejandro Colomar (man-pages) @ 2022-07-22 10:35 UTC (permalink / raw) To: G. Branden Robinson; +Cc: linux-man, groff On 7/22/22 04:14, G. Branden Robinson wrote: >> At least, _Exit(2) and _exit(2) point to the same page. nan(3) and >> NAN(3) don't, though! > > Pretty gross. A useful counterexample of good practice, though. > >> We can't blame the writers, since the identifiers have those names in >> C. Luckily, man(1) shows you the right page if you specify the right >> string. > > Yes, and at least they're closely related and from the same project. > > This is the only man page I know of that documents only simple (i.e., > not function-like) C preprocessor macros. You're more conversant with > libc-ish man pages so you may know of others, Actually, I don't. At least not previous to my introduction of intN_t(3type), which documents things like INT8_WIDTH and INT8_MAX (although I didn't [yet] create link pages with those name). > but this is the sort of > content that, as a user, I would prefer to find in, say, a "math.h(3)" > man page. Having these constants in a page by themselves does little to > situate them within the context of the C math library API. But I know I > have suggested this to you before. ;-) I remember. And I didn't ignore the suggestion; I've been thinking about it several times. There are various problems with documenting math.h(0) (section 0 was introduced for header files, but I don't know when, how, or why that happened; see the man-pages-posix repo for example. Other projects (Oracle? I don't remember well) use a subsection 3head, though. I think I don't like the idea of _only_ documenting macros in a header file doc. That is likely to produce a huge page such as system_data_types(7) once was, or queue(3). limits.h(0) is an exception in my head, since even though it's huge, all of them are related (all are limits), and it's easy to read. limits.h(0) has the advantage that you can navigate the page to see the limit that best fits your need; I would counter argue that with the following for the general case: man(1) supports regex search, so if you just want to search for all limits, man(1) supports regex searching, so you could do `man -k -s3def _MAX` to serach for *_MAX limits in a hypothetical 3def (or 3macro?) subsection dedicated to macros. See for example: $ man -s3type -k int._t int8_t (3type) - fixed-width basic integer types intN_t (3type) - fixed-width basic integer types uint8_t (3type) - fixed-width basic integer types uintN_t (3type) - fixed-width basic integer types > > I observe that the most popular simple macro of all, NULL, has no man > page. Oh, I had been thinking about it exactly yesterday, as I was wroking with the both loved and hated void(3type). Maybe NULL(3something) starts a brand new subsection soon. Do you have any preferences for the section name, since you mentioned it? :-) BTW, I think I didn't reply (or if I did was very short) to your comment that other languages may find it difficult to mirror our use of subsections, since their main section is already a subsection (e.g., 3pl). I'd say that since C is the native Unix language, and others are just... others?, I'd optimize for C, and let other languages find a way to document their things. It would be easy to say just go away, the man pages are for C, but I won't dare to say that, since I like man pages, and I'd like to see more documentation for languages that I sometimes have to use be in the form of man pages, so I'll try to come up with a more imaginative answer: how about using subsubsections of the form 3pl_type? At least it's a possibility. man(1) would handle them as any other subsection, but that's not a big problem. Maybe man(1) could develop a way to provide subsubsections... Colin, any ideas in this regard? > >> I feel a need to fix this lack of precision in the page titles. >> Unless someone opposes to it with some strong reason, which I don't >> expect. > > You never know. But keep in mind that a strong objection is not the > same thing as a strong reason. Yup. I expect the former, but not the latter. ;) > >> It'll take some time to do it, but if no-one speaks in a reasonable >> time, I'll start doing it :). > > We should all practice our scowling faces for anyone who dares to > promulgate man pages named "lS", "prIntf", or similar. Oh, I trust people is not so evil... I'll train the face just in case, though. Cheers, Alex > > Regards, > Branden -- Alejandro Colomar Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/ ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 10:35 ` Alejandro Colomar (man-pages) @ 2022-07-22 11:46 ` Alejandro Colomar 2022-07-22 19:03 ` G. Branden Robinson 2022-07-23 19:29 ` Ingo Schwarze 0 siblings, 2 replies; 27+ messages in thread From: Alejandro Colomar @ 2022-07-22 11:46 UTC (permalink / raw) To: G. Branden Robinson; +Cc: linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 1816 bytes --] Hi, On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote: > BTW, I think I didn't reply (or if I did was very short) to your comment > that other languages may find it difficult to mirror our use of > subsections, since their main section is already a subsection (e.g., > 3pl). I'd say that since C is the native Unix language, and others are > just... others?, I'd optimize for C, and let other languages find a way > to document their things. It would be easy to say just go away, the man > pages are for C, but I won't dare to say that, since I like man pages, > and I'd like to see more documentation for languages that I sometimes > have to use be in the form of man pages, so I'll try to come up with a > more imaginative answer: how about using subsubsections of the form > 3pl_type? At least it's a possibility. man(1) would handle them as any > other subsection, but that's not a big problem. Maybe man(1) could > develop a way to provide subsubsections... Colin, any ideas in this > regard? Or, maybe it's the time to write a whole new volume? I think there's a comparable difference between 3type and 3 than between 2 and 3 or 1 and 8, so it would be merited. I didn't do it before for two reasons: it might break software that assumes than Unix manuals use a single number followed by an optional string (I'd say it's not a fair assumption to say that man9 would be the last one ever used; if there's 9, there might be a 10 some day), and because other projects had already used 3type. But, that would start a clean namespace. Maybe it's worth it. How would you feel if I inaugurate man10 for types, and later man11 for non-function-like macros? :D Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 11:46 ` Alejandro Colomar @ 2022-07-22 19:03 ` G. Branden Robinson 2022-07-22 22:20 ` Alejandro Colomar 2022-07-23 19:29 ` Ingo Schwarze 1 sibling, 1 reply; 27+ messages in thread From: G. Branden Robinson @ 2022-07-22 19:03 UTC (permalink / raw) To: Alejandro Colomar; +Cc: linux-man, groff [-- Attachment #1: Type: text/plain, Size: 8023 bytes --] Hi Alex, At 2022-07-22T13:46:37+0200, Alejandro Colomar wrote: > On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote: > > BTW, I think I didn't reply (or if I did was very short) to your > > comment that other languages may find it difficult to mirror our use > > of subsections, since their main section is already a subsection > > (e.g., 3pl). In my (Debian-centric) experience, I see "3perl"--just a detail. > > I'd say that since C is the native Unix language, and others are > > just... others?, I'd optimize for C, and let other languages find a > > way to document their things. It would be easy to say just go away, > > the man pages are for C, but I won't dare to say that, since I like > > man pages, and I'd like to see more documentation for languages that > > I sometimes have to use be in the form of man pages, so I'll try to > > come up with a more imaginative answer: how about using > > subsubsections of the form 3pl_type? At least it's a possibility. > > man(1) would handle them as any other subsection, but that's not a > > big problem. Maybe man(1) could develop a way to provide > > subsubsections... Colin, any ideas in this regard? I don't see any reason to privilege the C language more than it already is. Let us review the default manual section titles--the material that appears in the center header by default when man pages are rendered. .\" Localize manual section titles for English. .de an*localize-strings . ds an*section1 General Commands Manual\" . ds an*section2 System Calls Manual\" . ds an*section3 Library Functions Manual\" . ds an*section4 Kernel Interfaces Manual\" . ds an*section5 File Formats Manual\" . ds an*section6 Games Manual\" . ds an*section7 Miscellaneous Information Manual\" . ds an*section8 System Manager's Manual\" . ds an*section9 Kernel Developer's Manual\" Literally none of this necessarily implies the use of C. Instead these sections are a coalition--perhaps an uneasy one--of three different categorical axes. (1) who needs the information--users, programmers, or administrators (2) whether the information is a kernel-invariant or not (3) the syntax of data presented to other system components I suggest that this arrangement survives not just due to blind inertia, though that may be the preponderant factor, but because in a POSIX system these categories remain fairly stable. One can bloat or shrink the kernel but there's always going to be a kernel. There is a sharp distinction between kernel (or supervisor) mode and user mode. Some users are more privileged than others, and perform administrative tasks. The file metaphor as a persistent array of (often seekable, often persistent) bytes is deeply entrenched. > Or, maybe it's the time to write a whole new volume? I think there's > a comparable difference between 3type and 3 than between 2 and 3 or 1 > and 8, so it would be merited. I didn't do it before for two reasons: > it might break software that assumes than Unix manuals use a single > number followed by an optional string (I'd say it's not a fair > assumption to say that man9 would be the last one ever used; if > there's 9, there might be a 10 some day), and because other projects > had already used 3type. > > But, that would start a clean namespace. Maybe it's worth it. > > How would you feel if I inaugurate man10 for types, and later man11 for > non-function-like macros? :D Permit me to play an unaccustomed role as a voice of conservatism. I don't think we need the section number, or even a section suffix, to communicate information about a data type. (A) Header files could be put in section 3 under their names as-is. We should remember that C standard library header files, per ISO C, need not be literally present on the file system; they can be provided by the compiler using unspecified means. I point this out to emphasize their exotic nature. They need not be ordinary files, though on POSIX systems we should expect this. I don't think inaugurating a "section 0" serves any use here, since C identifiers will not collide with them. We do not write a stand-alone man page for a member of a structure, so the element "h" of a hypothetical "struct math" will be documented in "math(3)", not "math.h(3)". (B) Collisions in C's name spaces are discouraged by common practice and seldom leveraged even where syntactically distinct. Functions and variables ("objects") are in the same name space in C, and data types and objects are so confusable[1] that in practice programmers treat them as being in the same name space. For example, structure tags enjoy their own name space but most novice and even many experienced C programmers are shaky on the fact. (This ignorance was compounded for decades by a common idiom of introducing type aliases ("typedefs"[2]) for structs as soon as they were declared.) The above points are why I think we not only don't need new sections of the manual, but that suffixes like "type" and "def" are not performing any service for the reader that isn't clearly and obviously communicated in the text of the man page, if it is written to a minimum level of quality. The synopsis will say what is needed, and within a programming language, names exposed by an API should not be ambiguous, so the suffix won't be necessary to aid the apropos/"man -k"-using reader. Here, let me do an impression. [tousels hair; puts on big glasses; becomes copyright rentier; indulges predatory, monopolistic practices] "Nine sections of the manual ought to be enough for anybody." Regards, Branden [1] https://en.wikipedia.org/wiki/Lexer_hack [2] A deceitful little term if there ever was one, because it does _nothing_ to enhance type conformance checking. Kernighan pointed out that "strong typing is not dimensional analysis" in his article "Why Pascal Is Not My Favorite Programming Language", when enumerating deficiencies of that language. Here's his example. type apple = integer; orange = integer; C works similarly. typedef int apple; typedef int orange; Kernighan failed to note that strong typing _could_ be dimensional analysis, if taken seriously. Perhaps he didn't because the same criticism could then be made of C, which had his name on it and proceeded to eat much of Pascal's lunch in the '80s and '90s--for reasons conspicuously distinct from the quality of its type checking. If you want real checking of a primitive type in C, you have to wrap it in a one-member struct. Even then you don't get range constraints, which are frequently valuable and which Pascal did support. Kernighan clucked in the same paper that range checks "seemed like a service, though they too exact a run-time penalty". In other words, they are costly. I wonder how we might measure the cost of failures to observe CERT'S INT{30,32}-C[3] in the quest for bragging rights about performance. Obviously its magnitude was recognized only in retrospect. Now, lest I seem hard on Kernighan here, let me note that, among other excellent points in the paper, his thorough trashing of Pascal's array handling, where the size was regarded as an integral part of the data type, was completely deserved. For those who haven't read the paper, this means that, yes, in pre-ISO Pascal, your function which operated on char arrays of length 4 would not be permitted to operate on char arrays of length 5. The compiler (or interpreter) would stop you. It is hard for me to imagine, as a workaday programmer, how Wirth let the language escape the laboratory with this defect. [3] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152052 [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 19:03 ` G. Branden Robinson @ 2022-07-22 22:20 ` Alejandro Colomar 0 siblings, 0 replies; 27+ messages in thread From: Alejandro Colomar @ 2022-07-22 22:20 UTC (permalink / raw) To: G. Branden Robinson; +Cc: linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 9940 bytes --] Hi Branden, On 7/22/22 21:03, G. Branden Robinson wrote: > Hi Alex, > > At 2022-07-22T13:46:37+0200, Alejandro Colomar wrote: >> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote: >>> BTW, I think I didn't reply (or if I did was very short) to your >>> comment that other languages may find it difficult to mirror our use >>> of subsections, since their main section is already a subsection >>> (e.g., 3pl). > > In my (Debian-centric) experience, I see "3perl"--just a detail. Yeah, I was talking from memory. You can tell how little perl I write. Most of my perl knowledge is PCRE (actually, I know quite a bit of that), but not much actual perl. > > .\" Localize manual section titles for English. > .de an*localize-strings > . ds an*section1 General Commands Manual\" > . ds an*section2 System Calls Manual\" > . ds an*section3 Library Functions Manual\" > . ds an*section4 Kernel Interfaces Manual\" 4 is special files for me. Kernel interfaces? that's a very unclear name to me. syscalls are also kernel interfaces. > . ds an*section5 File Formats Manual\" > . ds an*section6 Games Manual\" If we have a whole section for rogue(6), anything can get its own section ;) > . ds an*section7 Miscellaneous Information Manual\" > . ds an*section8 System Manager's Manual\" > . ds an*section9 Kernel Developer's Manual\" I wonder why the Linux kernel doesn't use this one. Did it ever do? I've seen some man9 pages floating around, but I don't know where they come from, and why they aren't in the Linux man-pages project. > > Literally none of this necessarily implies the use of C. Instead these > sections are a coalition--perhaps an uneasy one--of three different > categorical axes. > > (1) who needs the information--users, programmers, or administrators > (2) whether the information is a kernel-invariant or not > (3) the syntax of data presented to other system components > > I suggest that this arrangement survives not just due to blind inertia, > though that may be the preponderant factor, but because in a POSIX > system these categories remain fairly stable. One can bloat or shrink > the kernel but there's always going to be a kernel. There is a sharp > distinction between kernel (or supervisor) mode and user mode. Some > users are more privileged than others, and perform administrative tasks. > The file metaphor as a persistent array of (often seekable, often > persistent) bytes is deeply entrenched. That makes sense. Maybe 3type is good. > >> Or, maybe it's the time to write a whole new volume? I think there's >> a comparable difference between 3type and 3 than between 2 and 3 or 1 >> and 8, so it would be merited. I didn't do it before for two reasons: >> it might break software that assumes than Unix manuals use a single >> number followed by an optional string (I'd say it's not a fair >> assumption to say that man9 would be the last one ever used; if >> there's 9, there might be a 10 some day), and because other projects >> had already used 3type. >> >> But, that would start a clean namespace. Maybe it's worth it. >> >> How would you feel if I inaugurate man10 for types, and later man11 for >> non-function-like macros? :D > > Permit me to play an unaccustomed role as a voice of conservatism. I > don't think we need the section number, or even a section suffix, to > communicate information about a data type. > > (A) Header files could be put in section 3 under their names as-is. We > should remember that C standard library header files, per ISO C, > need not be literally present on the file system; they can be > provided by the compiler using unspecified means. I point this out > to emphasize their exotic nature. They need not be ordinary files, > though on POSIX systems we should expect this. I don't think > inaugurating a "section 0" serves any use here, since C identifiers > will not collide with them. We do not write a stand-alone man page > for a member of a structure, so the element "h" of a hypothetical > "struct math" will be documented in "math(3)", not "math.h(3)". Regarding structure tags, I aready defended the need to do something, when I added the -struct suffix (which was a poor man's subsection). If I were to rewrite the C library and kernel from scratch, without backwards compatibility, I'd fix many many things. But that train passed many years before I was born. For one example, we have stat(2) and stat(3type). Why did they exploit the fact that C allows calling a function and a struct the same? Don't ask me. But they did. So we need to be able to distinguish struct, union, and enum tags from global namespace identifiers. -struct was an option. man3type is much better, IMO (and already in use by Illumos and other systems). Maybe man10 would be going too far. But I strongly disagree with the initial temporary solution Michael and I decided at first, which was simply to avoid adding a link page stat(3) (and a few others) to system_data_types(7), even though we actually documented stat in system_data_types(7). There's a problem, and I want to solve it. > > (B) Collisions in C's name spaces are discouraged by common practice and > seldom leveraged even where syntactically distinct. Functions and > variables ("objects") are in the same name space in C, and data > types and objects are so confusable[1] that in practice programmers > treat them as being in the same name space. For example, structure > tags enjoy their own name space but most novice and even many > experienced C programmers are shaky on the fact. (This ignorance > was compounded for decades by a common idiom of introducing type > aliases ("typedefs"[2]) for structs as soon as they were declared.) I wish they used _s suffix for structs, or that at least they didn't abuse this C feature, but they did. It's too late to change that. > > The above points are why I think we not only don't need new sections of > the manual, but that suffixes like "type" and "def" are not performing > any service for the reader that isn't clearly and obviously communicated > in the text of the man page, if it is written to a minimum level of > quality. The synopsis will say what is needed, and within a programming > language, names exposed by an API should not be ambiguous, so the suffix > won't be necessary to aid the apropos/"man -k"-using reader. For the replies above, I'm strongly pushing for a 3type and a 3somethingelse subsections. Now, I'd really like to get a good name for the constants subsection. 3def seems to be too constrained to C's #define (and when C adds constexpr some day, man3def might be not a good name anymore). > > Here, let me do an impression. [tousels hair; puts on big glasses; > becomes copyright rentier; indulges predatory, monopolistic practices] > > "Nine sections of the manual ought to be enough for anybody." I think there's no need (yet) for new whole sections; you convinced me about that. :-) > > Regards, > Branden > > [1] https://en.wikipedia.org/wiki/Lexer_hack > [2] A deceitful little term if there ever was one, because it does > _nothing_ to enhance type conformance checking. Kernighan pointed > out that "strong typing is not dimensional analysis" in his article > "Why Pascal Is Not My Favorite Programming Language", when > enumerating deficiencies of that language. Here's his example. > > type > apple = integer; > orange = integer; > > C works similarly. > > typedef int apple; > typedef int orange; > > Kernighan failed to note that strong typing _could_ be dimensional > analysis, if taken seriously. Perhaps he didn't because the same > criticism could then be made of C, which had his name on it and > proceeded to eat much of Pascal's lunch in the '80s and '90s--for > reasons conspicuously distinct from the quality of its type > checking. > > If you want real checking of a primitive type in C, you have to wrap > it in a one-member struct. Even then you don't get range > constraints, which are frequently valuable and which Pascal did > support. Kernighan clucked in the same paper that range checks > "seemed like a service, though they too exact a run-time penalty". > In other words, they are costly. I wonder how we might measure the > cost of failures to observe CERT'S INT{30,32}-C[3] in the quest for > bragging rights about performance. Obviously its magnitude was > recognized only in retrospect. > > Now, lest I seem hard on Kernighan here, let me note that, among > other excellent points in the paper, his thorough trashing of > Pascal's array handling, where the size was regarded as an > integral part of the data type, was completely deserved. For those > who haven't read the paper, this means that, yes, in pre-ISO Pascal, > your function which operated on char arrays of length 4 would not be > permitted to operate on char arrays of length 5. The compiler (or > interpreter) would stop you. It is hard for me to imagine, as a > workaday programmer, how Wirth let the language escape the > laboratory with this defect. BTW, you can do something similar in C: int foo(int (*foo)[3]); int a[3], b[4]; foo(&a); foo(&b); // compiler error Not that I see much usefulness in it, but it's curious. > > [3] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152052 Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-22 11:46 ` Alejandro Colomar 2022-07-22 19:03 ` G. Branden Robinson @ 2022-07-23 19:29 ` Ingo Schwarze 2022-07-24 11:20 ` Alejandro Colomar (man-pages) 1 sibling, 1 reply; 27+ messages in thread From: Ingo Schwarze @ 2022-07-23 19:29 UTC (permalink / raw) To: Alejandro Colomar; +Cc: g.branden.robinson, linux-man, groff Hi Alejandro, On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote: > BTW, I think I didn't reply (or if I did was very short) to your comment > that other languages may find it difficult to mirror our use of > subsections, since their main section is already a subsection (e.g., > 3pl). Other languages are usually better off to live *outside* the $MANPATH and tell users to use "man -M" to access their documentation. For example, on OpenBSD, the TCL manuals live in /usr/local/lib/tcl/tcl8.5/man/ . Putting them into /usr/local/man/ would be quite disruptive because that would cause lots of clashes, including "apply", "break", "cd", "close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open", "puts", "pwd", "read", "socket", "time", and so on. I expect most other language will cause similar noise. Perl is better because the clashing names are mostly part of perlfunc(1), and the majority of other Perl manual page names contain colons. FORTRAN (traditionally in man3f) is also better because in this instance, the cryptic FORTAN six-letter identifiers become a virtue in so far as they prevent clashes. > I'd say that since C is the native Unix language, and others are > just... others?, I'd optimize for C, and let other languages find > a way to document their things. True - not because C is better or more worthy, but because looking up an identifier logically requires specifying the language, and as explained elsewhere, section suffixes are a poor solution for that. > It would be easy to say just go away, the man pages are for C, Absolutely not. While the manual page format may have some feature that are particularly well-suited to documenting C, it is not limited to that role. > but I won't dare to say that, since I like man pages, > and I'd like to see more documentation for languages that I sometimes > have to use be in the form of man pages, so I'll try to come up with a > more imaginative answer: how about using subsubsections of the form > 3pl_type? At least it's a possibility. man(1) would handle them as any > other subsection, but that's not a big problem. Maybe man(1) could > develop a way to provide subsubsections... Colin, any ideas in this > regard? See above. Alejandro Colomar wrote on Fri, Jul 22, 2022 at 01:46:37PM +0200: > Or, maybe it's the time to write a whole new volume? I think there's a > comparable difference between 3type and 3 than between 2 and 3 or 1 and > 8, so it would be merited. I didn't do it before for two reasons: it > might break software that assumes than Unix manuals use a single number > followed by an optional string (I'd say it's not a fair assumption to > say that man9 would be the last one ever used; if there's 9, there might > be a 10 some day), and because other projects had already used 3type. > > But, that would start a clean namespace. Maybe it's worth it. No, that would absolutely not be clean design. I advise strongly against it. First, concatening integer numbers and strings is often bad design because it significantly complicates processing in various way. For example, the traps set by the strtol(3) family of functions, in particular regarding trailing non-digit characters, are legendary. Bugs love the breeding ground. As another example, numerical vs. alphabetical sorting is a similarly famous trap, consider the difference of sort(1) vs. "sont -n". I'm sure you do *not* want to design a data type represented as a string such that the first part needs to be sorted numerically and the second part needs to be sorted alphanumerically - with not even a delimiting character in between. Less technically, having a small number of sections with non-desciptive names is fine; people get used to the meaning of 1 to 9. But when you start adding more sections, a scheme with non-descriptive names sooner or later becomes unsustainable. "What was section 42 again... i guess i'll have to look that up." So the design already strikes me as terrible even before starting to sonsider portability. I would expect no end of compatibility problems. * Most man(1) implementations will probably treat section 10 as a subsection of section 1. * While "man -s 10" may work with some man(1) implementations, "man 10 wchar_t" will fail saying man: No entry for 10 in the manual. on most. * When sorting, you will probably get 1, 10, 11, 2, 3, ... * I expect lots of code does char sc = '1' + sn - 1; asprintf(&fn, "%s.%c%s", name, sc, suffix); which leaves you with "name.:suffix" if sn == 10. * ... > How would you feel if I inaugurate man10 for types, and later man11 for > non-function-like macros? :D I wouldn't feel well at all. I think i'd prefer contracting a common cold to having to deal with that. Yours, Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-23 19:29 ` Ingo Schwarze @ 2022-07-24 11:20 ` Alejandro Colomar (man-pages) 2022-07-24 14:57 ` Ingo Schwarze 0 siblings, 1 reply; 27+ messages in thread From: Alejandro Colomar (man-pages) @ 2022-07-24 11:20 UTC (permalink / raw) To: Ingo Schwarze; +Cc: g.branden.robinson, linux-man, groff Hi Ingo, On 7/23/22 21:29, Ingo Schwarze wrote: > Hi Alejandro, > > On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote: > >> BTW, I think I didn't reply (or if I did was very short) to your comment >> that other languages may find it difficult to mirror our use of >> subsections, since their main section is already a subsection (e.g., >> 3pl). > > Other languages are usually better off to live *outside* the $MANPATH > and tell users to use "man -M" to access their documentation. > For example, on OpenBSD, the TCL manuals live > in /usr/local/lib/tcl/tcl8.5/man/ . > Putting them into /usr/local/man/ would be quite disruptive because > that would cause lots of clashes, including "apply", "break", "cd", > "close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open", > "puts", "pwd", "read", "socket", "time", and so on. I expect most > other language will cause similar noise. > Perl is better because the clashing names are mostly part of perlfunc(1), > and the majority of other Perl manual page names contain colons. > FORTRAN (traditionally in man3f) is also better because in this > instance, the cryptic FORTAN six-letter identifiers become a virtue > in so far as they prevent clashes. I'm not happy with this approach. I don't want to be typing paths for system stuff (your /usr/local is /usr in GNU/Linux systems; BTW, that's a thing I don't like at all from BSDs; IMO (and FHS's), /usr/local is for sysadmins to build from source; optional _packages_ should go to /opt). If you want to search pages in section 3type, `man -s3type regex`. However, having some pages in subsections of 3, and others in the main 3 section, is good for pages in subsections, but bad for pages in the main section (`man -s3 regex` would show all of the subsections' pages). That has a simple solution: move libc pages to man3c (and libm to man3m, ...). Since `man 3 printf` will continue working if this change is done, it doesn't seem to have backwards compatibility issues. Also, you can put unimportant subsections at the end of the search list, to not hide other more important pages. Cheers, Alex -- Alejandro Colomar Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/ ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-24 11:20 ` Alejandro Colomar (man-pages) @ 2022-07-24 14:57 ` Ingo Schwarze 2022-07-24 15:44 ` G. Branden Robinson 2022-07-24 16:17 ` man -M tcl " Alejandro Colomar 0 siblings, 2 replies; 27+ messages in thread From: Ingo Schwarze @ 2022-07-24 14:57 UTC (permalink / raw) To: Alejandro Colomar; +Cc: g.branden.robinson, linux-man, groff Hi Alejandro, Alejandro Colomar wrote on Sun, Jul 24, 2022 at 01:20:46PM +0200: > On 7/23/22 21:29, Ingo Schwarze wrote: >> On 7/22/22 12:35, Alejandro Colomar (man-pages) wrote: >>> BTW, I think I didn't reply (or if I did was very short) to your comment >>> that other languages may find it difficult to mirror our use of >>> subsections, since their main section is already a subsection (e.g., >>> 3pl). >> Other languages are usually better off to live *outside* the $MANPATH >> and tell users to use "man -M" to access their documentation. >> For example, on OpenBSD, the TCL manuals live >> in /usr/local/lib/tcl/tcl8.5/man/ . >> Putting them into /usr/local/man/ would be quite disruptive because >> that would cause lots of clashes, including "apply", "break", "cd", >> "close", "eval", "exec", "exit", "expr", "glob", "info", "join", "open", >> "puts", "pwd", "read", "socket", "time", and so on. I expect most >> other language will cause similar noise. >> Perl is better because the clashing names are mostly part of perlfunc(1), >> and the majority of other Perl manual page names contain colons. >> FORTRAN (traditionally in man3f) is also better because in this >> instance, the cryptic FORTAN six-letter identifiers become a virtue >> in so far as they prevent clashes. > I'm not happy with this approach. I don't want to be typing paths for > system stuff (your /usr/local is /usr in GNU/Linux systems; Then use an alias like alias tclman='man -M /usr/local/lib/tcl/tcl8.5/man/' It's not like users are normally using dozens of different languages at the same time, nor is the number of languages that provide a collection of manual pages very significant. So there isn't any real-world problem that needs solving. I even considered supporting aliases for manpath directories in man.conf(5), something like being able to say alias tcl /usr/local/lib/tcl/tcl8.5/man/ in /etc/man.conf and then being able to say man -M tcl open Disclaimer: the above is not a finished design, just a preliminary idea. But i'm very certain that -M or something derived from -M is the tool for the job and -s or something derived from -s is not. Because when you want a python manual page, you most definitely want "Python only" and it serves no purpose whatsoever to search through various trees and various sections, and least of all to badly design a string-based composite data type like "number_language": that causes all the ambiguity and confusion you are already discussing, and it is error-prone and fragile in the parser on top of that. Also, the concept of "for which language" and the concept of sections are orthognal. A programming langauge system usually provides utility programs (1), library functions (3), file formats(5), administration tools (8), and so on. The reason i didn't pursue the man.conf(5) alias idea so far is that the practical need for it is very limited. No one ever asked me for it as far as i recall, shell aliases do the job just fine. > If you want to search pages in section 3type, `man -s3type regex`. > However, having some pages in subsections of 3, and others in the main 3 > section, is good for pages in subsections, but bad for pages in the main > section (`man -s3 regex` would show all of the subsections' pages). > That has a simple solution: move libc pages to man3c (and libm to man3m, > ...). Since `man 3 printf` will continue working if this change is > done, it doesn't seem to have backwards compatibility issues. While the effect on the end user is indeed limited, you are proposing a massive file system reshuffle here that seems somewhat in search of a problem it wants to solve. Yes, systems do exist that traditionally use lots of section suffixes, so it *is* vital that man(1) implementations support such suffixes. But i claim that even in Solaris, those suffixes serve little practical purpose and users are best off simply ignoring them. > Also, you can put unimportant subsections at the end of the search > list, to not hide other more important pages. In *BSD, support for changing the search list was deleted years ago. That feature was an example of overengineering and useless complication. I don't recall even one single complaint from a user who wanted the feature back or explained what they were using it for. Not one person needing it in over half a decade since it was deleted... Yours, Ingo P.S. I moved this to the bottom because it is off-topic: > BTW, that's a thing I don't like at all from BSDs; IMO (and FHS's), Years ago, i tried to engage with the FHS maintainers, arguing that FHS is for Unux-like systems in general, and trying to contribute aspects relevant for *BSD. It was an uphill battle because the FHS community was very firmly entrenched as "Linux only"; some didn't even see a need to consider my comments at all, many comments were rejected saying something like "this particular point may be unusual on *BSD systems, but it is so important on Linux that we cannot possibly allow the established *BSD convention for this point in the FHS" even by those who were in principle willing to view the FHS as a guideline for Unix-like systems in general. On top of that, the group was almost dead, much less active than for example the groff community, and even that is a very small group. So ultimately, i gave up and left. Other OpenBSD developers laughed at me for even trying, essentially saying "Why do you even care about that Linux-only crap?" I still disagree and believe a file system hierarchy standard for Unix-like systems could potentially be useful. Just consider that "Where are the URW fonts?"-saga currently under way on this list as an example. But dismissing decade-old *BSD standards like the use of /usr/ for the base system and /usr/local/ for packages as a standard violation, and promoting /opt/ which is firmly a Linux-only invention, is not going to help. > /usr/local is for sysadmins to build from source; Doing that is *very* strongly discouraged on OpenBSD. If you only want to try out some unported software, do not install it at all or install it in your home directory. If you are serious about providing something system-wide, you are strongly expected to create a port, even if you do not publish the port, so it can be properly installed, kept track of by the package tools, controlled for collisions by the package tools, and cleanly uninstalled when its time comes. Creating a package is really simple. Just a few days ago, senior ports developers provided help to a user on our lists to do it properly for company-internal software that will never be published, and the thread was short because there wasn't that much to explain. I did build RPMs for SLES at one point in the past when working for a company, and i dimly remember looking at debian package build documentation occasionally, and both seemed significantly harder to both get started with and to master than BSD ports, so Linux users may have a stronger motivation to just "make install". Then again, there may also be a slight bias at work, what you are used to always feels simpler than what you are less familiar with. In any case, it is very intentional that OpenBSD does *not* provide a directory to users that they can "make install" to. > optional _packages_ should go to /opt). Not even Debian adheres to that. When i install an additional, optional package, i.e. one that Debian did not install by default when the system was originally installed, most of the time, that optional package goes to /usr/, not to /opt/. ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-24 14:57 ` Ingo Schwarze @ 2022-07-24 15:44 ` G. Branden Robinson 2022-07-24 17:07 ` FHS and packaging (was: All caps .TH page title) Alejandro Colomar 2022-07-27 16:05 ` All caps .TH page title Ingo Schwarze 2022-07-24 16:17 ` man -M tcl " Alejandro Colomar 1 sibling, 2 replies; 27+ messages in thread From: G. Branden Robinson @ 2022-07-24 15:44 UTC (permalink / raw) To: Ingo Schwarze; +Cc: Alejandro Colomar, linux-man, groff [-- Attachment #1: Type: text/plain, Size: 3058 bytes --] At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote: > But dismissing decade-old *BSD standards like the use of /usr/ for the > base system and /usr/local/ for packages as a standard violation, and > promoting /opt/ which is firmly a Linux-only invention, Oh, no it's not. I remember that thing from Solaris 2.3 or 2.4. Here's a slightly later source. https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html Your complaints about the Linux-centricity of the FHS can be explained largely by QuaNGO corporate politics.[1] The first Linux file system organization standard was called FSSTND and dates back to about 1994. But it had little or no organizational support or funding behind it. (It is hard to overstate how much Linux seemed like an underdog in those days.) You can read some further history at the usual reliable(?) source. https://en.wikipedia.org/wiki/Free_Standards_Group Since the FHS is fully under the purview of the Linux Foundation (LF), I don't think it's reasonable to expect any responses much different than what you describe. The LF exists to "promote Linux", which, as with any NGO with an open-ended mission, in practice means to sustain itself indefinitely via membership fees. (In the parlance of journalism, one can reliably correlate the "seriousness" of any NGO with the level of compensation enjoyed by its officers.) The benefits of membership are significant; you can utterly disregard the terms of the GNU GPL. If you are not a member and have transgressed, the Foundation will happily sell you an indulgence in the form of membership. Under this umbrella, the Linux kernel is effectively under the BSD license. Don't be shocked if even the disclosure of relevant copyright and license notices is a negotiable point. This is business. Under litigation you'd end up in much the same place, potentially with much more bad press. Monetary damages are the fuel that sustains the engine of civil procedure. Compliance and specific performance are distant concerns. Litigation to enforce the terms of the GPL is stridently characterized as discouraging and unproductive--we never ask "to whom?" or "of what?"--except insofar as it drives firms to the reassuring shelter of Foundation membership. You can see how it is helpful to characterize independent GPL plaintiffs as cranks and lunatics--moreover, you do LF a huge favor if, as such a plaintiff, you actually are a lunatic. This model is widely regarded as successful; indeed, when limiting your interviews to members of a cartel, reported levels of satisfaction with the organization are characteristically high. It dissolves otherwise. So guess what? The BSD camp did ultimately win the copyleft argument after all. Regards, Branden [1] Some would doubtless argue with the "qua" here. I remind the reader that copyrights are legal monopolies dispensed by the state. Copyright enforcement in the United States, for instance, was a _wholly_ civil matter until 1897, having spent over a century as a government-created tort. [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* FHS and packaging (was: All caps .TH page title) 2022-07-24 15:44 ` G. Branden Robinson @ 2022-07-24 17:07 ` Alejandro Colomar 2022-07-27 16:05 ` All caps .TH page title Ingo Schwarze 1 sibling, 0 replies; 27+ messages in thread From: Alejandro Colomar @ 2022-07-24 17:07 UTC (permalink / raw) To: G. Branden Robinson, Ingo Schwarze; +Cc: linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 7995 bytes --] Hi Ingo and Branden! On 7/24/22 16:57, Ingo Schwarze wrote: > P.S. > I moved this to the bottom because it is off-topic: > > Alejandro Colomar wrote on Sun, Jul 24, 2022 at 01:20:46PM +0200: >> BTW, that's a thing I don't like at all from BSDs; IMO (and FHS's), > > Years ago, i tried to engage with the FHS maintainers, arguing that > FHS is for Unux-like systems in general, and trying to contribute > aspects relevant for *BSD. It was an uphill battle because the > FHS community was very firmly entrenched as "Linux only"; some > didn't even see a need to consider my comments at all, many > comments were rejected saying something like "this particular point > may be unusual on *BSD systems, but it is so important on Linux that > we cannot possibly allow the established *BSD convention for this > point in the FHS" even by those who were in principle willing to > view the FHS as a guideline for Unix-like systems in general. > > On top of that, the group was almost dead, much less active than > for example the groff community, and even that is a very small group. > So ultimately, i gave up and left. Other OpenBSD developers laughed > at me for even trying, essentially saying "Why do you even care > about that Linux-only crap?" I still disagree and believe a > file system hierarchy standard for Unix-like systems could potentially > be useful. Just consider that "Where are the URW fonts?"-saga > currently under way on this list as an example. That you very much for your attempts to make the FHS be a real Unix standard. It's sad to read this. > > But dismissing decade-old *BSD standards like the use of /usr/ > for the base system and /usr/local/ for packages as a standard > violation, and promoting /opt/ which is firmly a Linux-only > invention, is not going to help. As Branden noted, this wasn't a Linux thing (I don't have the background he has, but I researched a lot about this, and found something like that). > >> /usr/local is for sysadmins to build from source; > > Doing that is *very* strongly discouraged on OpenBSD. I guess that's why the directory was reused in the BSDs to install ports (probably ports were installed by the sysadmin there, and by extension, ports are now always installed there, but that's just a guess). > If you only want > to try out some unported software, do not install it at all or install > it in your home directory. If you are serious about providing something > system-wide, you are strongly expected to create a port, even if you do > not publish the port, so it can be properly installed, kept track of > by the package tools, controlled for collisions by the package > tools, and cleanly uninstalled when its time comes. My use case is the following: As a programmer, I want to provide a reliable and useful Makefile (I know that's a rare thing to do, but I like to debug and optimize my Makefiles, both for performance and user experience, as we've already discussed). So, packagers/users should be able to pick a project of mine, and trust the Makefile to produce a good installation, even in parallel (as good as a Makefile can do, that is). I also want to test that my programs, when installed in the system, behave as expected, and that's one of the reasons I debug my programs by installing them, and running as a normal user would run them. Running in ~/bin is not the exact same thing as the system, and may not uncover some bugs. So, I run `make install` several times a minute sometimes when programming (or when writing manual pages). It also has the extra benefit that all of the paths are already configured by default, so I can omit paths (or skip configuring my user's PATH to include things like ~/bin and MANPATH to include ~/share/man). > > Creating a package is really simple. Just a few days ago, senior > ports developers provided help to a user on our lists to do it > properly for company-internal software that will never be published, > and the thread was short because there wasn't that much to explain. I don't know how easy it is to create a port. > > I did build RPMs for SLES at one point in the past when working > for a company, and i dimly remember looking at debian package build > documentation occasionally, and both seemed significantly harder > to both get started with and to master than BSD ports, so Linux > users may have a stronger motivation to just "make install". > Then again, there may also be a slight bias at work, what you are > used to always feels simpler than what you are less familiar with. But certainly, Linux packages are _hard_. I tried packaging for debian several projects of mine, and I always gave up. I have a list of things to read/watch for my next attempt, but I'm very lazy about it, since none of my previous attempts were good enough for my taste. > > In any case, it is very intentional that OpenBSD does *not* provide > a directory to users that they can "make install" to. > That's sad, but more sad is that BSDs took an existing path (/usr/local) to a different purpose. I had a discussion in NGINX Unit about it, and the decission for now has been: "support prefix=/usr/local for default manual installation through the Makefile, and let BSD users adjust to their preferred path". We were concerned that we might get collisions with the BSD port also installing in /usr/local, but that's the least evil (and considering BSD users don't typically run `make install`, it's not so bad). >> optional _packages_ should go to /opt). > > Not even Debian adheres to that. When i install an additional, > optional package, i.e. one that Debian did not install by default when > the system was originally installed, most of the time, that optional > package goes to /usr/, not to /opt/. Yeah. Since the line between optional and non-optional software is not so clear, some people have considered optional packages to be those that you install manually (i.e., .deb packages downloaded manually). So /opt has become the /usr/local of .deb packages. On 7/24/22 17:44, G. Branden Robinson wrote: > At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote: >> But dismissing decade-old *BSD standards like the use of /usr/ for the >> base system and /usr/local/ for packages as a standard violation, and >> promoting /opt/ which is firmly a Linux-only invention, > > Oh, no it's not. I remember that thing from Solaris 2.3 or 2.4. Here's > a slightly later source. > > https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html > [Branden's long rant about corporations, and NGOs] I agree with the rant. BTW, I have a longstanding issue with Debian packages. Branden, your experience with Debian might help, if you find some time. The thing is: I'd like to provide an official Debian package of the man-pages. There are several reasons for that: - Be able to use the full power of dpkg(1) to manage the installed files (`make install` is quite weak there). - Show users a good example of how to package their small programs, with the minimal stuff (but I aim to do it of very high quality). - Make it easier for users to install the pages directly from upstream, especially now that we haven't released in a year. (They can already `make install`, but that's not perfect, since they likely want dpkg(1) to manage the files. I know there are tools to autogenerate a package while installing with `make install`, but the quality of such packages is not something that I like.) - I only want to provide a .deb, for reasons related to your rant. So I'd like to provide a `make pkg-deb` target to create the package. Would you mind helping me do that? Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page title 2022-07-24 15:44 ` G. Branden Robinson 2022-07-24 17:07 ` FHS and packaging (was: All caps .TH page title) Alejandro Colomar @ 2022-07-27 16:05 ` Ingo Schwarze 2022-07-29 11:33 ` man0, man3head (was: All caps .TH page title) Alejandro Colomar 2022-07-29 11:43 ` BSD and GPL " Alejandro Colomar 1 sibling, 2 replies; 27+ messages in thread From: Ingo Schwarze @ 2022-07-27 16:05 UTC (permalink / raw) To: g.branden.robinson; +Cc: Alejandro Colomar, linux-man, groff Hi Branden, G. Branden Robinson wrote on Sun, Jul 24, 2022 at 10:44:47AM -0500: > At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote: >> But dismissing decade-old *BSD standards like the use of /usr/ for the >> base system and /usr/local/ for packages as a standard violation, and >> promoting /opt/ which is firmly a Linux-only invention, > Oh, no it's not. I remember that thing from Solaris 2.3 or 2.4. > Here's a slightly later source. > > https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html Oops, thanks for setting me right. Confirmed: > uname -a SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise > ls -al /opt total 2613 drwxr-xr-x 12 root other 13 Dec 31 2020 . drwxr-xr-x 19 root root 22 Aug 17 2018 .. drwxr-xr-x 4 root other 4 Feb 10 2015 bop drwxr-xr-x 25 root bin 29 Dec 1 2017 csw drwxr-xr-x 10 root sys 11 Aug 17 2018 developerstudio12.5 drwxr-xr-x 10 root sys 11 Aug 17 2018 developerstudio12.6 drwxr-xr-x 3 root root 3 Feb 10 2015 local drwxr-xr-x 12 root sys 12 Jan 22 2015 solarisstudio12.3 drwxr-xr-x 10 root sys 11 Dec 22 2015 solarisstudio12.4 drwxr-xr-x 13 root sys 13 Jan 22 2015 solstudio12.2 drwxr-xr-x 13 root sys 15 Oct 29 2015 SUNWspro -rw------- 1 root root 1311633 Oct 29 2015 uninstall_Sun_Studio_12.class drwxr-xr-x 3 root root 3 Feb 18 2015 VRTS It doesn't look as if modern Oracle Solaris uses it very extensively, but still, it does exist. [...] > Under this umbrella, the Linux kernel is effectively under the BSD > license. Except that free software projects cannot copy from it - that's quite a big BUT since allowing *everybody* to copy the code for any purpose is the central idea of the BSD license. ;-) [...] > The BSD camp did ultimately win the copyleft argument after all. I'm not so sure about that. The idea of the BSD license is to allow all uses that can be licensed to others according to the Berne Convention, retaining only those rights - essentially the moral rights, like being known as the author, and abuse of the Works for slandering the author being prohibited - that are inalienable in the first place according to the Berne Convention. Even if in effect, the Copyleft aspect of the GPL is not usually enforced against Foundation members, GPL code is far from as free as the Berne Convention would permit it to be, and far from as free as if it were under a BSD license. So essentially, you say that in practice, the GPL fails to attain the goals RMS designed it for, and i say that all the same, it has some serious and (hopefully) unintended detrimental side effects. I can't say i'm too happy with that. I certainly don't regard it as a win. It looks more like a lose-lose situation to me. But i don't think we can do much about that. Groff is still usable for most users without too much pain. Unless i want to contribute significant amounts of code, even i could do so. And to be fair, even if i wanted to contribute large amounts of code, the GPL would *not* prevent me from doing that - the thing the would stop me is the FSF CLA, which is an entirely different beast. Nuff' digression! Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
* man0, man3head (was: All caps .TH page title) 2022-07-27 16:05 ` All caps .TH page title Ingo Schwarze @ 2022-07-29 11:33 ` Alejandro Colomar 2022-07-29 12:31 ` Ingo Schwarze 2022-07-29 11:43 ` BSD and GPL " Alejandro Colomar 1 sibling, 1 reply; 27+ messages in thread From: Alejandro Colomar @ 2022-07-29 11:33 UTC (permalink / raw) To: Ingo Schwarze, g.branden.robinson; +Cc: linux-man [-- Attachment #1.1: Type: text/plain, Size: 4152 bytes --] [dropped groff@; irrelevant to them] Hi Branden, On 7/27/22 18:05, Ingo Schwarze wrote: > Hi Branden, > > G. Branden Robinson wrote on Sun, Jul 24, 2022 at 10:44:47AM -0500: >> At 2022-07-24T16:57:19+0200, Ingo Schwarze wrote: > >>> But dismissing decade-old *BSD standards like the use of /usr/ for the >>> base system and /usr/local/ for packages as a standard violation, and >>> promoting /opt/ which is firmly a Linux-only invention, > >> Oh, no it's not. I remember that thing from Solaris 2.3 or 2.4. >> Here's a slightly later source. >> >> https://docs.oracle.com/cd/E19455-01/805-6331/fsadm-17/index.html > > Oops, thanks for setting me right. > > Confirmed: > > > uname -a > SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise > > ls -al /opt > total 2613 > drwxr-xr-x 12 root other 13 Dec 31 2020 . > drwxr-xr-x 19 root root 22 Aug 17 2018 .. > drwxr-xr-x 4 root other 4 Feb 10 2015 bop > drwxr-xr-x 25 root bin 29 Dec 1 2017 csw > drwxr-xr-x 10 root sys 11 Aug 17 2018 developerstudio12.5 > drwxr-xr-x 10 root sys 11 Aug 17 2018 developerstudio12.6 > drwxr-xr-x 3 root root 3 Feb 10 2015 local > drwxr-xr-x 12 root sys 12 Jan 22 2015 solarisstudio12.3 > drwxr-xr-x 10 root sys 11 Dec 22 2015 solarisstudio12.4 > drwxr-xr-x 13 root sys 13 Jan 22 2015 solstudio12.2 > drwxr-xr-x 13 root sys 15 Oct 29 2015 SUNWspro > -rw------- 1 root root 1311633 Oct 29 2015 uninstall_Sun_Studio_12.class > drwxr-xr-x 3 root root 3 Feb 18 2015 VRTS > > It doesn't look as if modern Oracle Solaris uses it very extensively, > but still, it does exist. BTW, Branden, you asked why would I use section 0 for header files (although since the lists have been very hot these days, I won't care finding the exact email). I didn't inaugurate section 0 for that. I just followed existing practice. But, considering our discussions about the topic, and considering that I already changed CONFORMING TO to STANDARDS for consistency across all manual pages in existence, I'll reconsider. So, existing practice seems to be divided in: - Putting header files' pages directly in man3 (e.g., string(3)). Done by Linux man-pages, and BSDs (see BSD's sysexits(3)). I don't like the idea, especially if the page name doesn't have a trailing '.h', since they live in different namespaces. - Putting them in man3head. Done by some Oracle OSes (at least for some versions). - Putting them in man0. Done exclusively by the posix man pages. Not even something POSIX is responsible for, AFAIK, since we create the pages from the HTML source, which has noting to do with sections. Debian for example, changes this (see below). It seems to be the only place man0 is being used, and I have control over it. - Putting them in man7. Debian moves man0 pages to 7POSIX (but uses man7/). Since there's much division, and I have complete control over one (or even two if I can avoid Debian moving the pages to man7) of the variants, I could help unify header files manual pages across Unix systems by moving POSIX header file manual pages to man3head. I would also move the only page in the Linux man pages that is in man0 (added recently by me; sysexits.h(0)) and the man3 header pages from the Linux man-pages (such as string(3)) to man3head. Maybe Debian also gives up modifying upstream pages, since I'll make it really hard for them to "fix" man3type anyway (not on purpose, but they'll need to come up with a script to modify the link pages). That would leave us with the following situation: - Most header file pages would be in man3head (Oracle, POSIX, Linux). - BSDs still have a few (maybe only one?) header page in man3: sysexits(3). - Section 0 becomes desert, and maybe someone can give it a new use in the future, if a new section is ever need. Much nicer than before. Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: man0, man3head (was: All caps .TH page title) 2022-07-29 11:33 ` man0, man3head (was: All caps .TH page title) Alejandro Colomar @ 2022-07-29 12:31 ` Ingo Schwarze 0 siblings, 0 replies; 27+ messages in thread From: Ingo Schwarze @ 2022-07-29 12:31 UTC (permalink / raw) To: Alejandro Colomar; +Cc: g.branden.robinson, linux-man Hi Alejandro, Alejandro Colomar wrote on Fri, Jul 29, 2022 at 01:33:12PM +0200: > BTW, Branden, you asked why would I use section 0 for header files > (although since the lists have been very hot these days, I won't care > finding the exact email). > > I didn't inaugurate section 0 for that. > I just followed existing practice. I just looked at my forest (i.e., my collection of trees). Version 3 AT&T UNIX contains these files in man/man0/: * a macro file "aa" setting adjustment mode, indentation, and something for page breaks and header or footer lines * a file "basinf", kind of a quick start guide for UNIX, mostly about logging in and out, but also containing some remarks about programming and text processing * a sed script "headrc", rather cryptic * the famous permuted "index" file that used to be printed together with the UNIX manuals * a file "intro" containing the title page, preface, and introduction for the manuals * a file "toc" containing the table of contents of the manuals, in the typical section-then-alphabetic order * an ed script "tocrc", rather cryptic * a file "xx", obviously intended as a template for writing a new manual page The following systems use man/man0 for similar purposes: * v4, v6, PWB, v7, 32v, v8, v10, System III * 3BSD, 4.0BSD, 4.1BSD, 4.2BSD, 4.3BSD-Tahoe, 4.3BSD-Reno * 4.4BSD, 4.4BSD-Lite1, 4.4BSD-Lite2, NetBSD The exact content varies, but it's always used for auxiliary files like macros files, scripts, tools, and front matter. Usage of man/man0 is especially extensive in v10, which contains several man/man0 directories in various places with several dozen files contained in them. > But, considering our discussions about the topic, and > considering that I already changed CONFORMING TO to STANDARDS for > consistency across all manual pages in existence, I'll reconsider. > > So, existing practice seems to be divided in: > > - Putting header files' pages directly in man3 (e.g., string(3)). That practice is deprecated in OpenBSD: $ uname -a OpenBSD isnote.usta.de 7.1 GENERIC.MP#613 amd64 $ man string man: No entry for string in the manual. The way to get this information looks like this now: $ man -k In=string.h bit_alloc, bit_clear, bit_decl, bit_ffc, bit_ffs, bit_nclear, bit_nset, bit_set, bit_test, bitstr_size(3) - bit-string manipulation macros bzero, explicit_bzero(3) - write zeroes to a byte string memccpy(3) - copy string until character found memchr, memrchr(3) - locate byte in byte string memcmp(3) - compare byte string memcpy(3) - copy bytes memmem(3) - locate a byte substring in a byte string memmove(3) - copy bytes memset(3) - write a byte to byte string stpcpy, stpncpy(3) - copy strings strcat(3) - concatenate two strings without bounds checking strchr, index(3) - locate first occurrence of a character in a string strcmp, strncmp(3) - compare strings strcoll, strcoll_l(3) - compare strings according to current collation strcpy(3) - copy a string without bounds checking strcspn(3) - span the complement of a string strdup, strndup(3) - save a copy of a string strerror, strerror_l, strerror_r(3) - get error message string strlcpy, strlcat(3) - size-bounded string copying and concatenation strlen, strnlen(3) - find length of a string strmode(3) - convert inode status information into a symbolic string strncat(3) - concatenate a string with part of another strncpy(3) - copy part of a string to another strpbrk(3) - locate multiple characters in string strrchr, rindex(3) - locate last occurrence of a character in a string strsep(3) - separate strings strsignal(3) - get signal description string strspn(3) - span a string strstr, strcasestr(3) - locate a substring in a string strtok, strtok_r(3) - string token operations strxfrm, strxfrm_l(3) - transform a string under locale timingsafe_bcmp, timingsafe_memcmp(3) - timing-safe byte sequence comparisons audio, audioctl(4) - device-independent audio driver layer The reason for deprecating pages with names of the form "header_name(3)" is less that we don't want non-function-name pages in section 3 and more that we don't want manual pages for header files. I don't think FreeBSD and NetBSD deprecated such pages though; i still see lib/libc/string/string.3 in FreeBSD and NetBSD. > Done by Linux man-pages, and BSDs (see BSD's sysexits(3)). OpenBSD deprecated sysexits(3) - the whole feature, not only the name of the manual page. The DESCRIPTION in our page starts as follows: A few programs exit with the following non-portable error codes. Do not use them. While i highly respect Eric Allman, IMHO inventing "sysexits" was a bad idea. > I don't like the idea, especially if the page name doesn't have a > trailing '.h', since they live in different namespaces. > > - Putting them in man3head. > Done by some Oracle OSes (at least for some versions). Sounds like the least bad solution to me. > - Putting them in man0. > Done exclusively by the posix man pages. > Not even something POSIX is responsible for, AFAIK, > since we create the pages from the HTML source, > which has noting to do with sections. > Debian for example, changes this (see below). > It seems to be the only place man0 is being used, > and I have control over it. As explained above, man/man0 has traditionally been used for something else. The traditional use has lost much of its importance during the last two decades and right now, it doesn't seem likely to me that it might need to be revived, but still, not clashing with it seems better if it can be avoided. > - Putting them in man7. > Debian moves man0 pages to 7POSIX (but uses man7/). I don't like that. The "Miscellaneous Information Manual" (section 7) is mostly intended to be user-facing pages like editline(7), environ(7), glob(7), hier(7), man(7), packages(7), ports(7), re_format(7), symlink(7), utf8(7). Pages that are only interesting for programmers are less welcome in section 7, even though a few exceptions exist, for example operator(7). Manual pages for C header files clearly need to be part of the "Library Functions Manual" (section 3). > Since there's much division, and I have complete control over one (or > even two if I can avoid Debian moving the pages to man7) of the > variants, I could help unify header files manual pages across Unix > systems by moving POSIX header file manual pages to man3head. > > I would also move the only page in the Linux man pages that is in man0 > (added recently by me; sysexits.h(0)) and the man3 header pages from the > Linux man-pages (such as string(3)) to man3head. > > Maybe Debian also gives up modifying upstream pages, since I'll make it > really hard for them to "fix" man3type anyway (not on purpose, but > they'll need to come up with a script to modify the link pages). > > That would leave us with the following situation: > > - Most header file pages would be in man3head (Oracle, POSIX, Linux). That all makes sense to me. > - BSDs still have a few (maybe only one?) header page in man3: sysexits(3). Don't worry about that one, it is utterly unimportant, and almost nobody uses it. > - Section 0 becomes desert, and maybe someone can give it a new use in > the future, if a new section is ever need. As argued above, it might be best to not repurpose man/man0. Yours, Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
* BSD and GPL (was: All caps .TH page title) 2022-07-27 16:05 ` All caps .TH page title Ingo Schwarze 2022-07-29 11:33 ` man0, man3head (was: All caps .TH page title) Alejandro Colomar @ 2022-07-29 11:43 ` Alejandro Colomar 1 sibling, 0 replies; 27+ messages in thread From: Alejandro Colomar @ 2022-07-29 11:43 UTC (permalink / raw) To: Ingo Schwarze, g.branden.robinson; +Cc: linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 2863 bytes --] Hi Ingo and Branden, On 7/27/22 18:05, Ingo Schwarze wrote: > [...] >> Under this umbrella, the Linux kernel is effectively under the BSD >> license. > > Except that free software projects cannot copy from it - that's > quite a big BUT since allowing *everybody* to copy the code for > any purpose is the central idea of the BSD license. ;-) > > [...] >> The BSD camp did ultimately win the copyleft argument after all. > > I'm not so sure about that. The idea of the BSD license is to > allow all uses that can be licensed to others according to the Berne > Convention, retaining only those rights - essentially the moral rights, > like being known as the author, and abuse of the Works for slandering > the author being prohibited - that are inalienable in the first place > according to the Berne Convention. > > Even if in effect, the Copyleft aspect of the GPL is not usually > enforced against Foundation members, GPL code is far from as free > as the Berne Convention would permit it to be, and far from as free > as if it were under a BSD license. > > So essentially, you say that in practice, the GPL fails to attain > the goals RMS designed it for, and i say that all the same, it has > some serious and (hopefully) unintended detrimental side effects. > > I can't say i'm too happy with that. > I certainly don't regard it as a win. > It looks more like a lose-lose situation to me. > > But i don't think we can do much about that. Groff is still > usable for most users without too much pain. Unless i want to > contribute significant amounts of code, even i could do so. > And to be fair, even if i wanted to contribute large amounts of > code, the GPL would *not* prevent me from doing that - the thing > the would stop me is the FSF CLA, which is an entirely different > beast. Yes, essentially, the kernel is BSD-licensed to big corporations paying to the FSF, but GPL to free software programmers. BSDs are BSD for everyone. I'm still using GPL for my own things, but I'm not happy at all with this situation, and considered several times giving up and using BSD licenses. I still don't, because I'm not accepting the lose-lose situation. But at the same time, I'd like to make a note here that the intention matters more than the license to me, and my intention is that my code can be useful to other open-source programmers. So, if anyone needs to use code of mine in other open-source code, don't be intimidated by the license, and you can always ask me for an exception to the license. The end goal is that open-source code improves. Non-open-source is still strictly limited to GPL regarding my own code. The paragraph above is not an invitation to break GPL in my code. Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* man -M tcl (was: All caps .TH page title) 2022-07-24 14:57 ` Ingo Schwarze 2022-07-24 15:44 ` G. Branden Robinson @ 2022-07-24 16:17 ` Alejandro Colomar 2022-07-27 15:32 ` Ingo Schwarze 1 sibling, 1 reply; 27+ messages in thread From: Alejandro Colomar @ 2022-07-24 16:17 UTC (permalink / raw) To: Ingo Schwarze; +Cc: g.branden.robinson, linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 4327 bytes --] Hi Ingo, On 7/24/22 16:57, Ingo Schwarze wrote: [...] >> I'm not happy with this approach. I don't want to be typing paths for >> system stuff (your /usr/local is /usr in GNU/Linux systems; > > Then use an alias like > > alias tclman='man -M /usr/local/lib/tcl/tcl8.5/man/' > > It's not like users are normally using dozens of different languages > at the same time, nor is the number of languages that provide a > collection of manual pages very significant. So there isn't any > real-world problem that needs solving. > > I even considered supporting aliases for manpath directories > in man.conf(5), something like being able to say > > alias tcl /usr/local/lib/tcl/tcl8.5/man/ > > in /etc/man.conf and then being able to say > > man -M tcl open Now we're talking. I've long missed such a thing. Let's please discuss it. I wondered for a long time what happens if you create subdirs within a man? section. How do man(1)s handle </usr/share/man/man3/python/foo.3>? Would your -M require that the pages live in a separate path? Or could it support subpaths? > > Disclaimer: the above is not a finished design, just a preliminary > idea. But i'm very certain that -M or something derived from -M > is the tool for the job and -s or something derived from -s is not. > Because when you want a python manual page, you most definitely want > "Python only" and it serves no purpose whatsoever to search through > various trees and various sections, and least of all to badly design > a string-based composite data type like "number_language": that causes > all the ambiguity and confusion you are already discussing, and > it is error-prone and fragile in the parser on top of that. > > Also, the concept of "for which language" and the concept of sections > are orthognal. A programming langauge system usually provides > utility programs (1), library functions (3), file formats(5), > administration tools (8), and so on. Agree. > > The reason i didn't pursue the man.conf(5) alias idea so far is that > the practical need for it is very limited. No one ever asked me for > it as far as i recall, shell aliases do the job just fine. > > >> If you want to search pages in section 3type, `man -s3type regex`. >> However, having some pages in subsections of 3, and others in the main 3 >> section, is good for pages in subsections, but bad for pages in the main >> section (`man -s3 regex` would show all of the subsections' pages). >> That has a simple solution: move libc pages to man3c (and libm to man3m, >> ...). Since `man 3 printf` will continue working if this change is >> done, it doesn't seem to have backwards compatibility issues. > > While the effect on the end user is indeed limited, you are proposing > a massive file system reshuffle here that seems somewhat in search of > a problem it wants to solve. Yes, systems do exist that traditionally > use lots of section suffixes, so it *is* vital that man(1) implementations > support such suffixes. But i claim that even in Solaris, those suffixes > serve little practical purpose and users are best off simply ignoring > them. I do want to document types (even if I had to document them in function pages, I'd add link pages with the name of the type, for reasons already stated in several other threads). Types are better documented standalone, IMO, also for reasons I detailed in several other threads. And, as also discussed in several threads, having type pages in man3 is problematic (collisions, ambiguity (does foo(3) refer to a function or a type? foo(3type) does certainly refer to a type; and foo(3[c]) should certainly refer to a function). > >> Also, you can put unimportant subsections at the end of the search >> list, to not hide other more important pages. > > In *BSD, support for changing the search list was deleted years ago. > That feature was an example of overengineering and useless complication. > I don't recall even one single complaint from a user who wanted the > feature back or explained what they were using it for. Not one > person needing it in over half a decade since it was deleted... Okay. Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: man -M tcl (was: All caps .TH page title) 2022-07-24 16:17 ` man -M tcl " Alejandro Colomar @ 2022-07-27 15:32 ` Ingo Schwarze 2022-07-29 12:03 ` Alejandro Colomar 0 siblings, 1 reply; 27+ messages in thread From: Ingo Schwarze @ 2022-07-27 15:32 UTC (permalink / raw) To: Alejandro Colomar; +Cc: g.branden.robinson, linux-man, groff Hi Alejandro, Alejandro Colomar wrote on Sun, Jul 24, 2022 at 06:17:40PM +0200: > On 7/24/22 16:57, Ingo Schwarze wrote: >> I even considered supporting aliases for manpath directories >> in man.conf(5), something like being able to say >> >> alias tcl /usr/local/lib/tcl/tcl8.5/man/ >> >> in /etc/man.conf and then being able to say >> >> man -M tcl open > Now we're talking. I've long missed such a thing. > Let's please discuss it. Well, it wouldn't be the first time i implemented a feature in mandoc that is not very urgently needed on OpenBSD but where the main need came from Linux (or Illumos or MacOS, for that matter). If it doesn't cause disruption or excessive complexity, which seems unlikely in this case, we can consider it. Do you think this would really get used in practice? If so, as a motivation, it would be useful to collect a handful of languages that would use this. So far, i'm mostly aware of Tcl and Tk. And of the POSIX manual pages. Of course i can't speak for man-db and other man(1) implementations. Then again, even if other man(1) implementations would not follow, maybe having -M aliases might be useful even in a single implementation. Users of the others could still use shell aliases. One side effect useful for myself would be that i could do, in man.conf(5), alias B /usr/share/man alias P /usr/local/man alias X /usr/X11R6/man and then say man -kMB sha256 when i only want to base system pages and be undisturbed by ports pages - right now, i type "-M /usr/share/man" relatively often. Or say man -MP:B to play with precedence. > I wondered for a long time what happens if you create subdirs within a > man? section. How do man(1)s handle </usr/share/man/man3/python/foo.3>? On *BSD systems, that typically means: The architecture-specific library function foo(3) for the "python" hardware architecture. Here are a few examples from OpenBSD: /usr/share/man/man1/sparc64/mksuncd.1 /usr/share/man/man2/armv7/arm_sync_icache.2 /usr/share/man/man2/i386/i386_iopl.2 /usr/share/man/man3/octeon/cacheflush.3 /usr/share/man/man3/sgi/get_fpc_csr.3 /usr/share/man/man4/alpha/irongate.4 /usr/share/man/man4/amd64/mpbios.4 /usr/share/man/man4/luna88k/cbus.4 /usr/share/man/man4/macppc/openpic.4 /usr/share/man/man4/powerpc64/opalcons.4 /usr/share/man/man4/riscv64/sfgpio.4 /usr/share/man/man5/sparc64/ldom.conf.5 /usr/share/man/man8/hppa/boot.8 /usr/share/man/man8/macppc/pdisk.8 /usr/share/man/man8/sgi/sgivol.8 /usr/share/man/man8/sparc64/ldomctl.8 So, lets assume i'm on a amd64 machine and want to learn how logical domains (a virtualization feature implemented in SPARC hardware) are configured: $ arch OpenBSD.amd64 $ man ldom.conf man: No entry for ldom.conf in the manual. $ man -S sparc64 ldom.conf [...] NAME ldom.conf Logical Domain configuration [...] Note that i said -S there, not -s nor -M. So i advise against doing that for python: the namespace is already taken for a different purpose. Using /usr/share/man/python/man3/foo.3 would be similarly bad, that usually means: The translation of /usr/share/man/man3/foo.3 into the natural language "python". Typical examples on OpenBSD: /usr/local/man/ja/man1/w3m.1 /usr/local/man/pt_BR/man6/wesnoth.6 /usr/local/man/de/man1/dvipdf.1 > Would your -M require that the pages live in a separate path? > Or could it support subpaths? The directory -M points to needs to contain the usual man1/ man3/ man5/ etc. subdirectories. Where exactly you put that doesn't matter for man(1), but i strongly advise against putting it into /usr/share/man because all the namespace in there is already taken for other purposes, and putting it in there anyway is likely to confuse tools like makewhatis(8), mandb(8), catman(8), and apropos(1). If a language is so large that it comes with a whole suite of manual pages (as ooposed to a language like awk(1) small enough to be documented in a single page), then that language is likely to already have its own directory for data files, typically somewhere below /usr/share/. Maybe it even has its own directory below /usr/share/doc/ already. For example, /usr/share/doc/python already exists on Debian, so /usr/share/doc/python/man/man[1-5]/... might one be reasoable choice, albeit certainly not the only option. Yours, Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: man -M tcl (was: All caps .TH page title) 2022-07-27 15:32 ` Ingo Schwarze @ 2022-07-29 12:03 ` Alejandro Colomar 2022-07-29 13:22 ` Ingo Schwarze 0 siblings, 1 reply; 27+ messages in thread From: Alejandro Colomar @ 2022-07-29 12:03 UTC (permalink / raw) To: Ingo Schwarze; +Cc: g.branden.robinson, linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 6474 bytes --] Hi Ingo, On 7/27/22 17:32, Ingo Schwarze wrote: > Hi Alejandro, > > Alejandro Colomar wrote on Sun, Jul 24, 2022 at 06:17:40PM +0200: >> On 7/24/22 16:57, Ingo Schwarze wrote: > >>> I even considered supporting aliases for manpath directories >>> in man.conf(5), something like being able to say >>> >>> alias tcl /usr/local/lib/tcl/tcl8.5/man/ >>> >>> in /etc/man.conf and then being able to say >>> >>> man -M tcl open > >> Now we're talking. I've long missed such a thing. >> Let's please discuss it. > > Well, it wouldn't be the first time i implemented a feature in mandoc > that is not very urgently needed on OpenBSD but where the main need > came from Linux (or Illumos or MacOS, for that matter). > > If it doesn't cause disruption or excessive complexity, > which seems unlikely in this case, we can consider it. > > Do you think this would really get used in practice? I don't know. I haven't received any such feature requests from users. But I've many times had the feeling that the man hierarchy is so flat and is so overpopulated (as soon as you start installing some packages; especially those that document their API in man3) that it's hard to find what you want. That's one of the reasons that I think man3type, man3const are better outside of man3. > > If so, as a motivation, it would be useful to collect a handful > of languages that would use this. So far, i'm mostly aware of > Tcl and Tk. And of the POSIX manual pages. BTW, I guess you also have the POSIX man pages in BSDs. Do they come from the kernel repo that I maintain, or do you have your own separate repos? > > Of course i can't speak for man-db and other man(1) implementations. > Then again, even if other man(1) implementations would not follow, > maybe having -M aliases might be useful even in a single implementation. > Users of the others could still use shell aliases. Yep. I don't think that should be a problem. > > One side effect useful for myself would be that i could do, in man.conf(5), > > alias B /usr/share/man > alias P /usr/local/man > alias X /usr/X11R6/man > > and then say > > man -kMB sha256 > > when i only want to base system pages and be undisturbed by ports > pages - right now, i type "-M /usr/share/man" relatively often. Yes, I also often want to compare the differences between the last release of the man-pages, and the page that I'm modifying, and that would be simpler with such a feature. > > Or say > > man -MP:B > > to play with precedence. > >> I wondered for a long time what happens if you create subdirs within a >> man? section. How do man(1)s handle </usr/share/man/man3/python/foo.3>? > > On *BSD systems, that typically means: > > The architecture-specific library function foo(3) > for the "python" hardware architecture. > > Here are a few examples from OpenBSD: > > /usr/share/man/man1/sparc64/mksuncd.1 > /usr/share/man/man2/armv7/arm_sync_icache.2 > /usr/share/man/man2/i386/i386_iopl.2 > /usr/share/man/man3/octeon/cacheflush.3 > /usr/share/man/man3/sgi/get_fpc_csr.3 > /usr/share/man/man4/alpha/irongate.4 > /usr/share/man/man4/amd64/mpbios.4 > /usr/share/man/man4/luna88k/cbus.4 > /usr/share/man/man4/macppc/openpic.4 > /usr/share/man/man4/powerpc64/opalcons.4 > /usr/share/man/man4/riscv64/sfgpio.4 > /usr/share/man/man5/sparc64/ldom.conf.5 > /usr/share/man/man8/hppa/boot.8 > /usr/share/man/man8/macppc/pdisk.8 > /usr/share/man/man8/sgi/sgivol.8 > /usr/share/man/man8/sparc64/ldomctl.8 > > So, lets assume i'm on a amd64 machine and want to learn how > logical domains (a virtualization feature implemented in > SPARC hardware) are configured: > > $ arch > OpenBSD.amd64 > $ man ldom.conf > man: No entry for ldom.conf in the manual. > $ man -S sparc64 ldom.conf > [...] > NAME > ldom.conf Logical Domain configuration > [...] > > Note that i said -S there, not -s nor -M. > > So i advise against doing that for python: the namespace is already > taken for a different purpose. Yeah, idea discarded. > > Using /usr/share/man/python/man3/foo.3 would be similarly bad, > that usually means: > > The translation of /usr/share/man/man3/foo.3 > into the natural language "python". > > Typical examples on OpenBSD: > > /usr/local/man/ja/man1/w3m.1 > /usr/local/man/pt_BR/man6/wesnoth.6 > /usr/local/man/de/man1/dvipdf.1 Makes, sense; also discarded. > >> Would your -M require that the pages live in a separate path? >> Or could it support subpaths? > > The directory -M points to needs to contain the usual man1/ man3/ > man5/ etc. subdirectories. Where exactly you put that doesn't > matter for man(1), but i strongly advise against putting it into > /usr/share/man because all the namespace in there is already > taken for other purposes, and putting it in there anyway is likely > to confuse tools like makewhatis(8), mandb(8), catman(8), > and apropos(1). > > If a language is so large that it comes with a whole suite of manual > pages (as ooposed to a language like awk(1) small enough to be > documented in a single page), then that language is likely to > already have its own directory for data files, typically somewhere > below /usr/share/. Maybe it even has its own directory below > /usr/share/doc/ already. For example, /usr/share/doc/python > already exists on Debian, so /usr/share/doc/python/man/man[1-5]/... > might one be reasoable choice, albeit certainly not the only option. I'd like to discuss about the best place to recommend putting manual pages. Do you know if any projects (Tcl and Tk maybe) are already using a specific path for man pages? I think something under $docdir would be a nice place. The FHS mentions[1] </usr[/local]/share/doc>. GNU specifies[2] that $docdir should be </usr/local/share/doc/pkgname> for a </usr/local> prefix. So they seem to agree in where $docdir lives. Then we could make the pkg-specific mandirs be </usr/local/share/doc/pkgname/man/man*>. What are your thoughts? Cheers, Alex [1]: <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html> [2]: <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html> -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: man -M tcl (was: All caps .TH page title) 2022-07-29 12:03 ` Alejandro Colomar @ 2022-07-29 13:22 ` Ingo Schwarze 2022-07-29 13:27 ` Alejandro Colomar 0 siblings, 1 reply; 27+ messages in thread From: Ingo Schwarze @ 2022-07-29 13:22 UTC (permalink / raw) To: Alejandro Colomar; +Cc: g.branden.robinson, linux-man, groff Hi Alejandro, Alejandro Colomar wrote on Fri, Jul 29, 2022 at 02:03:51PM +0200: > BTW, I guess you also have the POSIX man pages in BSDs. Do they come > from the kernel repo that I maintain, or do you have your own separate > repos? $ less /usr/ports/books/man-pages-posix/Makefile [...] COMMENT = POSIX manual pages DISTNAME = man-pages-posix-2013-a MASTER_SITES=https://www.kernel.org/pub/linux/docs/man-pages/man-pages-posix/ EXTRACT_SUFX=.tar.xz [...] DOCDIR = ${PREFIX}/share/doc/posix [...] # mapping of categories: source => destination MANS = 0p 3 MANS += 1p 1 MANS += 3p 3 [...] I don't know off the top of my head what FreeBSD and NetBSD ports do, but you can no doubt look it up if you are interested. > I'd like to discuss about the best place to recommend putting manual pages. > > Do you know if any projects (Tcl and Tk maybe) are already using a > specific path for man pages? $ pkg_locate /man/man | grep -v :/usr/local/man | \ sed 's/[^\/]*\/[^\/]*$//' | sed -E 's/(.*):(.*):(.*)/\3:\1/' | \ sort | uniq > tmp.txt $ vi tmp.txt # minimal manual cleanup $ cat tmp.txt /usr/local/cyrus/man/:cyrus-imapd-3.4.4 /usr/local/heirloom-doctools/man/:heirloom-doctools-191015p0 /usr/local/jdk-1.8.0/man/:jdk-1.8.0.332.b09.1v0 /usr/local/jdk-11/man/:jdk-11.0.15.10.1v0 /usr/local/jdk-17/man/:jdk-17.0.3.7.1v0 /usr/local/lib/eopenssl/man/:openssl-1.0.2up4 /usr/local/lib/eopenssl11/man/:libretls-3.5.2 /usr/local/lib/eopenssl11/man/:openssl-1.1.1q /usr/local/lib/eopenssl30/man/:openssl-3.0.5 /usr/local/lib/erlang21/man/:erlang-21.3.8.24v0 /usr/local/lib/erlang21/man/:erlang-wx-21.3.8.24v0 /usr/local/lib/node_modules/npm/man/:node-16.15.1v0 /usr/local/lib/ruby/gems/3.1/gems/kramdown-2.3.1/man/:ruby31-kramdown-2.3.1 /usr/local/lib/stk/4.0.1/man/:STk-4.0.1p19 /usr/local/lib/swipl-7.6.0/xpce/prolog/lib/:swi-prolog-7.6.0p15 /usr/local/lib/tcl/tcl8.5/man/:tcl-8.5.19p6 /usr/local/lib/tcl/tcl8.6/man/:tcl-8.6.12 /usr/local/lib/tcl/tk8.5/man/:tk-8.5.19p2 /usr/local/lib/tcl/tk8.6/man/:tk-8.6.12 /usr/local/plan9/man/:plan9port-20210323 /usr/local/riscv32-esp-elf/share/man/:riscv32-esp-elf-binutils-2.35.1.2020.1223 /usr/local/riscv32-esp-elf/share/man/:riscv32-esp-elf-gcc-8.4.0.2021.2 /usr/local/riscv32-esp-elf/share/man/:riscv32-esp-elf-gdb-2.35.1.2021.2 /usr/local/share/doc/posix/man/:man-pages-posix-2017a /usr/local/share/docbook2X/xslt/:docbook2x-0.8.8p5 /usr/local/share/fish/man/:fish-3.4.1p3 /usr/local/share/libowfat/man/:libowfat-0.32p0 /usr/local/share/man/:smplayer-22.2.0 /usr/local/xtensa-esp32-elf/share/man/:xtensa-esp32-elf-binutils-2.35.1.2020.1223p0 /usr/local/xtensa-esp32-elf/share/man/:xtensa-esp32-elf-gcc-8.4.0.2021.2 /usr/local/xtensa-esp32-elf/share/man/:xtensa-esp32-elf-gdb-2.35.1.2021.2p0 /usr/local/xtensa-esp32s2-elf/share/man/:xtensa-esp32s2-elf-binutils-2.35.1.2020.1223 /usr/local/xtensa-esp32s2-elf/share/man/:xtensa-esp32s2-elf-gcc-8.4.0.2021.2 /usr/local/xtensa-esp32s2-elf/share/man/:xtensa-esp32s2-elf-gdb-2.35.1.2021.2 /usr/local/xtensa-esp32s3-elf/share/man/:xtensa-esp32s3-elf-binutils-2.35.1.2020.1223 /usr/local/xtensa-esp32s3-elf/share/man/:xtensa-esp32s3-elf-gcc-8.4.0.2021.2 /usr/local/xtensa-esp32s3-elf/share/man/:xtensa-esp32s3-elf-gdb-2.35.1.2021.2 /usr/local/xtensa-lx106-elf/share/man/:xtensa-lx106-elf-binutils-2.32p0 /usr/local/xtensa-lx106-elf/share/man/:xtensa-lx106-elf-gcc-10.2.0p3 I can't say so far if those paths are the default paths upstream chose or in how many cases the OpenBSD porter chose them instead. Finding out requires looking at each of these about 35 ports individually. > I think something under $docdir would be a nice place. > > The FHS mentions[1] </usr[/local]/share/doc>. > GNU specifies[2] that $docdir should be </usr/local/share/doc/pkgname> > for a </usr/local> prefix. > > So they seem to agree in where $docdir lives. Then we could make the > pkg-specific mandirs be </usr/local/share/doc/pkgname/man/man*>. > > What are your thoughts? Yes, even though /usr/local/share/doc/pkgname/man/man* is a bit long, it makes more sense than paths like /usr/local/cyrus/man/ /usr/local/heirloom-doctools/man/ /usr/local/lib/erlang21/man/ /usr/local/lib/node_modules/npm/man/ /usr/local/lib/stk/4.0.1/man/ /usr/local/lib/tcl/tcl8.6/man/ /usr/local/plan9/man/ /usr/local/share/fish/man/ Then again, *if* we go the -M alias way, these paths are only ever used in the man.conf(5) file. So where exactly they are has no major impact on the user and is more a matter of system cleanliness. Yours, Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: man -M tcl (was: All caps .TH page title) 2022-07-29 13:22 ` Ingo Schwarze @ 2022-07-29 13:27 ` Alejandro Colomar 0 siblings, 0 replies; 27+ messages in thread From: Alejandro Colomar @ 2022-07-29 13:27 UTC (permalink / raw) To: Ingo Schwarze; +Cc: g.branden.robinson, linux-man, groff [-- Attachment #1.1: Type: text/plain, Size: 1062 bytes --] On 7/29/22 15:22, Ingo Schwarze wrote: >> What are your thoughts? > > Yes, even though /usr/local/share/doc/pkgname/man/man* is a bit long, > it makes more sense than paths like > > /usr/local/cyrus/man/ > /usr/local/heirloom-doctools/man/ > /usr/local/lib/erlang21/man/ > /usr/local/lib/node_modules/npm/man/ > /usr/local/lib/stk/4.0.1/man/ > /usr/local/lib/tcl/tcl8.6/man/ > /usr/local/plan9/man/ > /usr/local/share/fish/man/ > > Then again, *if* we go the -M alias way, these paths are only > ever used in the man.conf(5) file. So where exactly they are > has no major impact on the user and is more a matter of system > cleanliness. Yeah, I do want to have system cleanliness, especially to help programmers organizing their file hierarchy know where they should put things. So, let it be </usr/local/share/doc/pkgname/man/man*>. I'll have a look at the POSIX man pages and see if there's something I can do there. Thanks, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: All caps .TH page name 2022-07-21 18:36 ` G. Branden Robinson 2022-07-21 23:16 ` All caps .TH page title Alejandro Colomar @ 2022-07-22 16:19 ` Ingo Schwarze 1 sibling, 0 replies; 27+ messages in thread From: Ingo Schwarze @ 2022-07-22 16:19 UTC (permalink / raw) To: G. Branden Robinson; +Cc: Alejandro Colomar, linux-man Hi Branden, G. Branden Robinson wrote on Thu, Jul 21, 2022 at 01:36:20PM -0500: > I would take a jaundiced view toward any software project > that distinguished its man page names, whether internally or from > others' solely by a difference in lettercase. Inside one project, causing such clashes is certainly a bad idea. But just as same-case clashes sometimes happen accidentally - consider this on OpenBSD with the "mono" package installed - $ man mdoc | sed -n 4p mdoc - semantic markup language for formatting manual pages $ man 1 mdoc | sed -n 4p mdoc - Mono documentation management tool different-case clashes also happen occasionally: $ man -T ascii err | sed -n '4p;5p' err, verr, errc, verrc, errx, verrx, warn, vwarn, warnc, vwarnc, warnx, vwarnx - formatted error messages $ man -T ascii ERR | sed -n '4p' ERR - OpenSSL error codes $ man -T ascii sha256 | sed -n '4p;5p' md5, sha1, sha256, sha512 - calculate a message digest (checksum) for a file $ man -T ascii SHA256 | sed -n '4p;5p;6p;7p' SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update, SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384, SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, SHA512_Final - Secure Hash Algorithm Admittedly, these clashes are extremely rare, so it's not a big issue either way, at least not for practical purposes. Yours, Ingo ^ permalink raw reply [flat|nested] 27+ messages in thread
end of thread, other threads:[~2022-07-29 13:28 UTC | newest] Thread overview: 27+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-07-21 14:29 All caps .TH page name Alejandro Colomar 2022-07-21 18:36 ` G. Branden Robinson 2022-07-21 23:16 ` All caps .TH page title Alejandro Colomar 2022-07-22 0:22 ` Colin Watson 2022-07-22 1:34 ` G. Branden Robinson 2022-07-22 4:07 ` G. Branden Robinson 2022-07-22 14:44 ` Ingo Schwarze 2022-07-22 2:14 ` G. Branden Robinson 2022-07-22 10:35 ` Alejandro Colomar (man-pages) 2022-07-22 11:46 ` Alejandro Colomar 2022-07-22 19:03 ` G. Branden Robinson 2022-07-22 22:20 ` Alejandro Colomar 2022-07-23 19:29 ` Ingo Schwarze 2022-07-24 11:20 ` Alejandro Colomar (man-pages) 2022-07-24 14:57 ` Ingo Schwarze 2022-07-24 15:44 ` G. Branden Robinson 2022-07-24 17:07 ` FHS and packaging (was: All caps .TH page title) Alejandro Colomar 2022-07-27 16:05 ` All caps .TH page title Ingo Schwarze 2022-07-29 11:33 ` man0, man3head (was: All caps .TH page title) Alejandro Colomar 2022-07-29 12:31 ` Ingo Schwarze 2022-07-29 11:43 ` BSD and GPL " Alejandro Colomar 2022-07-24 16:17 ` man -M tcl " Alejandro Colomar 2022-07-27 15:32 ` Ingo Schwarze 2022-07-29 12:03 ` Alejandro Colomar 2022-07-29 13:22 ` Ingo Schwarze 2022-07-29 13:27 ` Alejandro Colomar 2022-07-22 16:19 ` All caps .TH page name Ingo Schwarze
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.