On Wed, Feb 12, 2014 at 09:13:43PM +0100, Ingo Schwarze wrote: > 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. >
i wouldn;t want this to happen at all, to be honest. i just wanted to point out that you could do it. try adding it to the page, then see how ugly it becomes. jmc > > 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
