Hi Jason, Jason McIntyre wrote on Mon, Feb 10, 2014 at 08:29:24AM +0000: > On Sun, Feb 09, 2014 at 03:19:36PM -0800, Philip Guenther wrote: >> On Sun, Feb 9, 2014 at 3:02 PM, d...@genunix.com <d...@genunix.com> wrote:
>>> Question .. where do I get all the man pages? I have some of them >>> but then others are absent : >>> >>> # man reboot >>> REBOOT(8) OpenBSD System Manager's Manual REBOOT(8) >>> [...] >>> SEE ALSO >>> reboot(2), utmp(5), boot_alpha(8), boot_amd64(8), boot_hp300(8), >>> boot_hppa(8), boot_hppa64(8), boot_i386(8), boot_luna88k(8), >>> boot_macppc(8), boot_mvme68k(8), boot_mvme88k(8), boot_sparc(8), >>> boot_sparc64(8), boot_vax(8), boot_zaurus(8), rc.d(8), rc.shutdown(8), >>> savecore(8), shutdown(8), sync(8) >> Hmm, that may be incorrect notation for the pages which are >> architecture specific: the boot_*(8) manpages are in the architecture >> specific sections. They can be seen on all platforms using the -S >> option to man, ala: >> >> man -S i386 boot_i386 >> man -S sparc boot_sparc >> ...etc >> >> By default, man uses the architecture that you're running, so if >> you're running on i386, you should be able to just say >> man boot_i386 >> >> I'm not 100% sure if the cross-references in the SEE ALSO section >> should be indicating that; I could have sworn that I saw syntax like >> "whatever(8/i386)" elsewhere. Jason, Ingo, what the Right Thing here? > we use 8/i386 notation in man -k (apropos) output, not in man pages, > though you can use 8/i386 instead of just 8, and mandoc won;t complain. > i suspect ingo will tell us it'll break other tools. Actually, both mandoc and groff would be happy with stuff like .Xr boot_alpha 8/alpha and off the top of my head, i don't see which tools might break. Certainly not our Perl makewhatis(8), it doesn't parse that deeply. And mandocdb(8) does the right thing out of the box, using it, you can even search for pages containing arch-specific .Xrs: $ ./obj/apropos Xr=/alpha halt(8), reboot(8) - stopping and restarting the system $ ./obj/apropos -O Xr Xr=/alpha halt(8), reboot(8) - [...] # rc.conf(8) # boot_alpha(8/alpha) # [...] Given that neither groff_mdoc(7) nor mdoc(7) mention this possibility, i'm not 100% sure all exotic tools will cope, but i don't consider problems very likely. Most tools are quite lenient when parsing macro arguments, roff and groff traditionally do almost no validation, and most other tools refrain from parsing random content macros, anyway. So if you see value in making this explicit, i'd suggest asking on the groff list whether anybody else expects problems, and if not, documenting and using it. > in this case it seems clear the intent is to list all the boot_ pages and > assume the reader will understand. it's a fair assumption. For boot_alpha(8), it's nearly obvious; but stuff like inb(2) may confuse readers quite a bit unless the arch is made explicit. > the alternative is to remove all the platform dependent cross > references. That seems like a bad idea. > i don;t really have a problem with its current format. we do have other > pages that reference (by neccesity) platform dependent pages, though > they themselves are usually platform dependent. Sure, that mitigates the issue. Yours, Ingo
