* fill gaps in arch.in and lib.in @ 2011-10-16 15:06 Ingo Schwarze [not found] ` <20111016155419.GC8820@harkle.home.gateway> 0 siblings, 1 reply; 6+ messages in thread From: Ingo Schwarze @ 2011-10-16 15:06 UTC (permalink / raw) To: tech; +Cc: jmc Hi, while looking at groff, i noticed that our arch.in is swiss cheese. I'm quite sure we want to be able to properly render manuals from other operating systems, even on platforms that OpenBSD does not run on, so i'm asking for OKs for the patch below. What i added here is: - missing OpenBSD architectures, even if they are still work in progress (beagle, ia64, palm) - tier I and II NetBSD architectures - architectures listed in current groff However, i'm not quite sure what to do about the documentation. Adding all these to mdoc(7) seems clearly excessive; there is no need to advertise stuff like "pc532", that's merely needed for groff compatibility. Stripping down the list to what OpenBSD currently supports is not a good choice either; that would require maintaining multiple copies of mdoc.7, since NetBSD probably wants a longer list. Maybe, in place of "It must be one of...": The mandoc(1) utility supports a fixed list of architectures; manuals for all architectures can be formatted on any architecture and operating system. Writing manuals, however, requires sticking to the architectures supported by the respective operating system. To provide some examples, the following are common architectures: alpha, amd64, hp300, i386, ia64, landisk, mac68k, macppc, mvme68k, sparc, sparc64, vax, zaurus. In addition to these, the following are valid for OpenBSD: armish, aviion, beagle, hppa, hppa64, loongson, mvme88k, palm, sgi, socppc, solbourne. And the following are valid for NetBSD: acorn26, acorn32, algor, amiga, amigappc, arc, atari, bebox, cats, cesfic, cobalt, dreamcast, emips, evbarm, evbmips, evbppc, evbsh3, ews4800mips, hp700, hpcarm, hpcmips, hpcsh, ibmnws, iyonix, luna68k, mipsco, mmeye, mvmeppc, netwinder, news68k, newsmips, next68k, ofppc, pmax, prep, rs6000, sandpoint, sbmips, sgimips, shark, sun2, sun3, x68k, xen. I'm not completely convinced of that approach either, but can't think of anything better. Or should we just drop the whole list? I don't like that idea either... Thoughts? Ingo Index: arch.in =================================================================== RCS file: /cvs/src/usr.bin/mandoc/arch.in,v retrieving revision 1.5 diff -u -p -r1.5 arch.in --- arch.in 26 Sep 2010 15:10:20 -0000 1.5 +++ arch.in 16 Oct 2011 14:13:20 -0000 @@ -26,31 +26,85 @@ * REMEMBER TO ADD NEW ARCHITECTURES TO MDOC.7! */ +LINE("acorn26", "Acorn26") +LINE("acorn32", "Acorn32") +LINE("algor", "Algor") LINE("alpha", "Alpha") LINE("amd64", "AMD64") LINE("amiga", "Amiga") +LINE("amigappc", "AmigaPPC") LINE("arc", "ARC") LINE("arm", "ARM") +LINE("arm26", "ARM26") +LINE("arm32", "ARM32") LINE("armish", "ARMISH") LINE("aviion", "AViiON") +LINE("atari", "ATARI") +LINE("beagle", "Beagle") +LINE("bebox", "BeBox") +LINE("cats", "cats") +LINE("cesfic", "CESFIC") +LINE("cobalt", "Cobalt") +LINE("dreamcast", "Dreamcast") +LINE("emips", "EMIPS") +LINE("evbarm", "evbARM") +LINE("evbmips", "evbMIPS") +LINE("evbppc", "evbPPC") +LINE("evbsh3", "evbSH3") +LINE("ews4800mips", "EWS4800MIPS") LINE("hp300", "HP300") +LINE("hp700", "HP700") +LINE("hpcarm", "HPCARM") +LINE("hpcmips", "HPCMIPS") +LINE("hpcsh", "HPCSH") LINE("hppa", "HPPA") LINE("hppa64", "HPPA64") +LINE("ia64", "ia64") LINE("i386", "i386") +LINE("ibmnws", "IBMNWS") +LINE("iyonix", "Iyonix") LINE("landisk", "LANDISK") LINE("loongson", "Loongson") +LINE("luna68k", "Luna68k") LINE("luna88k", "Luna88k") +LINE("m68k", "m68k") LINE("mac68k", "Mac68k") LINE("macppc", "MacPPC") +LINE("mips", "MIPS") LINE("mips64", "MIPS64") +LINE("mipsco", "MIPSCo") +LINE("mmeye", "mmEye") LINE("mvme68k", "MVME68k") LINE("mvme88k", "MVME88k") LINE("mvmeppc", "MVMEPPC") +LINE("netwinder", "NetWinder") +LINE("news68k", "NeWS68k") +LINE("newsmips", "NeWSMIPS") +LINE("next68k", "NeXT68k") +LINE("ofppc", "OFPPC") +LINE("palm", "Palm") +LINE("pc532", "PC532") +LINE("playstation2", "PlayStation2") LINE("pmax", "PMAX") +LINE("pmppc", "pmPPC") +LINE("powerpc", "PowerPC") +LINE("prep", "PReP") +LINE("rs6000", "RS6000") +LINE("sandpoint", "Sandpoint") +LINE("sbmips", "SBMIPS") LINE("sgi", "SGI") +LINE("sgimips", "SGIMIPS") +LINE("sh3", "SH3") +LINE("shark", "Shark") LINE("socppc", "SOCPPC") +LINE("solbourne", "Solbourne") LINE("sparc", "SPARC") LINE("sparc64", "SPARC64") +LINE("sun2", "Sun2") LINE("sun3", "Sun3") +LINE("tahoe", "Tahoe") LINE("vax", "VAX") +LINE("x68k", "X68k") +LINE("x86_64", "x86_64") +LINE("xen", "Xen") LINE("zaurus", "Zaurus") Index: lib.in =================================================================== RCS file: /cvs/src/usr.bin/mandoc/lib.in,v retrieving revision 1.6 diff -u -p -r1.6 lib.in --- lib.in 20 Sep 2011 23:36:22 -0000 1.6 +++ lib.in 16 Oct 2011 14:13:20 -0000 @@ -81,6 +81,7 @@ LINE("librpcsvc", "RPC Service Library ( LINE("librt", "POSIX Real\\-time Library (librt, -lrt)") LINE("libsdp", "Bluetooth Service Discovery Protocol User Library (libsdp, \\-lsdp)") LINE("libssp", "Buffer Overflow Protection Library (libssp, \\-lssp)") +LINE("libSystem", "System Library (libSystem, \\-lSystem)") LINE("libtermcap", "Termcap Access Library (libtermcap, \\-ltermcap)") LINE("libterminfo", "Terminal Information Library (libterminfo, \\-lterminfo)") LINE("libthr", "1:1 Threading Library (libthr, \\-lthr)") -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 6+ messages in thread
[parent not found: <20111016155419.GC8820@harkle.home.gateway>]
* Re: fill gaps in arch.in and lib.in [not found] ` <20111016155419.GC8820@harkle.home.gateway> @ 2011-10-16 16:10 ` Ingo Schwarze 2011-10-16 16:14 ` Kristaps Dzonsons 0 siblings, 1 reply; 6+ messages in thread From: Ingo Schwarze @ 2011-10-16 16:10 UTC (permalink / raw) To: Jason McIntyre; +Cc: tech Hi Jason, Jason McIntyre wrote on Sun, Oct 16, 2011 at 04:53:55PM +0059: > On Sun, Oct 16, 2011 at 05:06:30PM +0200, Ingo Schwarze wrote: >> while looking at groff, i noticed that our arch.in is swiss cheese. >> I'm quite sure we want to be able to properly render manuals from >> other operating systems, even on platforms that OpenBSD does not >> run on, so i'm asking for OKs for the patch below. >> >> What i added here is: >> - missing OpenBSD architectures, even if they are still >> work in progress (beagle, ia64, palm) > beagle was removed, no (under the "never again" banner, if memory > serves). I doubt that; look at http://www.openbsd.org/plat.html http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/beagle/dev/prcm.c It is listed below "Active porting efforts", the code is not in the Attic, and miod@ committed beagle-only fixes a few weeks ago. > for me, i want to know what platforms are valid on the os i'm writing > on. as an openbsd user, i don;t care what netbsd supports (and vice > versa, i'm sure). what will you do when other systems start using mandoc? > > i think there is a need for local changes here. i dislike listing > everything. i would also dislike listing nothing. That makes a lot of sense, it seems you are right that maintaining local documantation changes is less effort and much more useful here than trying to serve the same docs to everyone. Thus, if i get an OK from tech@mdocml, i'm going to commit the code changes to bsd.lv and openbsd.org, but leave the manuals alone. And after that, i'm going to try and push the missing *BSD architectures upstream to groff as well. Thanks, Ingo Index: arch.in =================================================================== RCS file: /cvs/src/usr.bin/mandoc/arch.in,v retrieving revision 1.5 diff -u -p -r1.5 arch.in --- arch.in 26 Sep 2010 15:10:20 -0000 1.5 +++ arch.in 16 Oct 2011 14:13:20 -0000 @@ -26,31 +26,85 @@ * REMEMBER TO ADD NEW ARCHITECTURES TO MDOC.7! */ +LINE("acorn26", "Acorn26") +LINE("acorn32", "Acorn32") +LINE("algor", "Algor") LINE("alpha", "Alpha") LINE("amd64", "AMD64") LINE("amiga", "Amiga") +LINE("amigappc", "AmigaPPC") LINE("arc", "ARC") LINE("arm", "ARM") +LINE("arm26", "ARM26") +LINE("arm32", "ARM32") LINE("armish", "ARMISH") LINE("aviion", "AViiON") +LINE("atari", "ATARI") +LINE("beagle", "Beagle") +LINE("bebox", "BeBox") +LINE("cats", "cats") +LINE("cesfic", "CESFIC") +LINE("cobalt", "Cobalt") +LINE("dreamcast", "Dreamcast") +LINE("emips", "EMIPS") +LINE("evbarm", "evbARM") +LINE("evbmips", "evbMIPS") +LINE("evbppc", "evbPPC") +LINE("evbsh3", "evbSH3") +LINE("ews4800mips", "EWS4800MIPS") LINE("hp300", "HP300") +LINE("hp700", "HP700") +LINE("hpcarm", "HPCARM") +LINE("hpcmips", "HPCMIPS") +LINE("hpcsh", "HPCSH") LINE("hppa", "HPPA") LINE("hppa64", "HPPA64") +LINE("ia64", "ia64") LINE("i386", "i386") +LINE("ibmnws", "IBMNWS") +LINE("iyonix", "Iyonix") LINE("landisk", "LANDISK") LINE("loongson", "Loongson") +LINE("luna68k", "Luna68k") LINE("luna88k", "Luna88k") +LINE("m68k", "m68k") LINE("mac68k", "Mac68k") LINE("macppc", "MacPPC") +LINE("mips", "MIPS") LINE("mips64", "MIPS64") +LINE("mipsco", "MIPSCo") +LINE("mmeye", "mmEye") LINE("mvme68k", "MVME68k") LINE("mvme88k", "MVME88k") LINE("mvmeppc", "MVMEPPC") +LINE("netwinder", "NetWinder") +LINE("news68k", "NeWS68k") +LINE("newsmips", "NeWSMIPS") +LINE("next68k", "NeXT68k") +LINE("ofppc", "OFPPC") +LINE("palm", "Palm") +LINE("pc532", "PC532") +LINE("playstation2", "PlayStation2") LINE("pmax", "PMAX") +LINE("pmppc", "pmPPC") +LINE("powerpc", "PowerPC") +LINE("prep", "PReP") +LINE("rs6000", "RS6000") +LINE("sandpoint", "Sandpoint") +LINE("sbmips", "SBMIPS") LINE("sgi", "SGI") +LINE("sgimips", "SGIMIPS") +LINE("sh3", "SH3") +LINE("shark", "Shark") LINE("socppc", "SOCPPC") +LINE("solbourne", "Solbourne") LINE("sparc", "SPARC") LINE("sparc64", "SPARC64") +LINE("sun2", "Sun2") LINE("sun3", "Sun3") +LINE("tahoe", "Tahoe") LINE("vax", "VAX") +LINE("x68k", "X68k") +LINE("x86_64", "x86_64") +LINE("xen", "Xen") LINE("zaurus", "Zaurus") Index: lib.in =================================================================== RCS file: /cvs/src/usr.bin/mandoc/lib.in,v retrieving revision 1.6 diff -u -p -r1.6 lib.in --- lib.in 20 Sep 2011 23:36:22 -0000 1.6 +++ lib.in 16 Oct 2011 14:13:20 -0000 @@ -81,6 +81,7 @@ LINE("librpcsvc", "RPC Service Library ( LINE("librt", "POSIX Real\\-time Library (librt, -lrt)") LINE("libsdp", "Bluetooth Service Discovery Protocol User Library (libsdp, \\-lsdp)") LINE("libssp", "Buffer Overflow Protection Library (libssp, \\-lssp)") +LINE("libSystem", "System Library (libSystem, \\-lSystem)") LINE("libtermcap", "Termcap Access Library (libtermcap, \\-ltermcap)") LINE("libterminfo", "Terminal Information Library (libterminfo, \\-lterminfo)") LINE("libthr", "1:1 Threading Library (libthr, \\-lthr)") -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: fill gaps in arch.in and lib.in 2011-10-16 16:10 ` Ingo Schwarze @ 2011-10-16 16:14 ` Kristaps Dzonsons 2011-10-16 16:42 ` Ingo Schwarze 0 siblings, 1 reply; 6+ messages in thread From: Kristaps Dzonsons @ 2011-10-16 16:14 UTC (permalink / raw) To: tech; +Cc: Ingo Schwarze, Jason McIntyre On 16/10/2011 18:10, Ingo Schwarze wrote: > Hi Jason, > > Jason McIntyre wrote on Sun, Oct 16, 2011 at 04:53:55PM +0059: >> On Sun, Oct 16, 2011 at 05:06:30PM +0200, Ingo Schwarze wrote: > >>> while looking at groff, i noticed that our arch.in is swiss cheese. >>> I'm quite sure we want to be able to properly render manuals from >>> other operating systems, even on platforms that OpenBSD does not >>> run on, so i'm asking for OKs for the patch below. >>> >>> What i added here is: >>> - missing OpenBSD architectures, even if they are still >>> work in progress (beagle, ia64, palm) > >> beagle was removed, no (under the "never again" banner, if memory >> serves). > > I doubt that; look at > > http://www.openbsd.org/plat.html > http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/beagle/dev/prcm.c > > It is listed below "Active porting efforts", the code is not > in the Attic, and miod@ committed beagle-only fixes a few weeks > ago. > >> for me, i want to know what platforms are valid on the os i'm writing >> on. as an openbsd user, i don;t care what netbsd supports (and vice >> versa, i'm sure). what will you do when other systems start using mandoc? >> >> i think there is a need for local changes here. i dislike listing >> everything. i would also dislike listing nothing. > > That makes a lot of sense, it seems you are right that maintaining > local documantation changes is less effort and much more useful here > than trying to serve the same docs to everyone. > > Thus, if i get an OK from tech@mdocml, i'm going to commit the > code changes to bsd.lv and openbsd.org, but leave the manuals > alone. Hi Ingo, Thanks for doing this research! It looks fine with me---the arch patch, I mean. As for the manual page, perhaps we can narrow it down to the "big ones" and simply mention that most others modern platforms are supported? The big ones being i386, amd64, sparc, sparc64---whatever. I agree that a Big List is a bad idea, as well as listing nothing. This would strike a nice balance. Thanks, Kristaps -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: fill gaps in arch.in and lib.in 2011-10-16 16:14 ` Kristaps Dzonsons @ 2011-10-16 16:42 ` Ingo Schwarze 2011-10-24 16:30 ` Kristaps Dzonsons 0 siblings, 1 reply; 6+ messages in thread From: Ingo Schwarze @ 2011-10-16 16:42 UTC (permalink / raw) To: tech; +Cc: Jason McIntyre Hi Kristaps, Kristaps Dzonsons wrote on Sun, Oct 16, 2011 at 06:14:52PM +0200: > As for the manual page, perhaps we can narrow it down to the "big > ones" and simply mention that most others modern platforms are > supported? The big ones being i386, amd64, sparc, > sparc64---whatever. I agree that a Big List is a bad idea, as well > as listing nothing. This would strike a nice balance. Maybe even simpler: In the individual operating systems, let's keep everything as it is. In the generic bsd.lv version, let's just put something like: The list of supported architectures varies by operating system. For the full list of all architectures recognized by mandoc(1), see the file arch.in in the source distribution. Note that mandoc(1) can format manuals for all architectures and operating systems on any platform. Yours, Ingo -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: fill gaps in arch.in and lib.in 2011-10-16 16:42 ` Ingo Schwarze @ 2011-10-24 16:30 ` Kristaps Dzonsons 2011-10-24 22:25 ` Ingo Schwarze 0 siblings, 1 reply; 6+ messages in thread From: Kristaps Dzonsons @ 2011-10-24 16:30 UTC (permalink / raw) To: tech; +Cc: Ingo Schwarze, Jason McIntyre On 10/16/11 18:42, Ingo Schwarze wrote: > Hi Kristaps, > > Kristaps Dzonsons wrote on Sun, Oct 16, 2011 at 06:14:52PM +0200: > >> As for the manual page, perhaps we can narrow it down to the "big >> ones" and simply mention that most others modern platforms are >> supported? The big ones being i386, amd64, sparc, >> sparc64---whatever. I agree that a Big List is a bad idea, as well >> as listing nothing. This would strike a nice balance. > > Maybe even simpler: > > In the individual operating systems, let's keep everything as it is. > > In the generic bsd.lv version, let's just put something like: > > The list of supported architectures varies by operating system. > For the full list of all architectures recognized by mandoc(1), > see the file arch.in in the source distribution. > > Note that mandoc(1) can format manuals for all architectures > and operating systems on any platform. Ingo, I think this is fine, considering the options. Of course a remaining option is to make a mandoc_arch(7) manual, but then we'd need mandoc_lib(7) too... but that's just messy. I think a similar note should be put into the `Lb' documentation in referring to libraries in lib.in, too, as it's not a fixed set. Thoughts? Kristaps -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: fill gaps in arch.in and lib.in 2011-10-24 16:30 ` Kristaps Dzonsons @ 2011-10-24 22:25 ` Ingo Schwarze 0 siblings, 0 replies; 6+ messages in thread From: Ingo Schwarze @ 2011-10-24 22:25 UTC (permalink / raw) To: tech; +Cc: Jason McIntyre Hi Kristaps, Kristaps Dzonsons wrote on Mon, Oct 24, 2011 at 06:30:12PM +0200: > On 10/16/11 18:42, Ingo Schwarze wrote: >> Kristaps Dzonsons wrote on Sun, Oct 16, 2011 at 06:14:52PM +0200: >>> As for the manual page, perhaps we can narrow it down to the "big >>> ones" and simply mention that most others modern platforms are >>> supported? The big ones being i386, amd64, sparc, >>> sparc64---whatever. I agree that a Big List is a bad idea, as well >>> as listing nothing. This would strike a nice balance. >> Maybe even simpler: >> >> In the individual operating systems, let's keep everything as it is. >> >> In the generic bsd.lv version, let's just put something like: >> >> The list of supported architectures varies by operating system. >> For the full list of all architectures recognized by mandoc(1), >> see the file arch.in in the source distribution. >> >> Note that mandoc(1) can format manuals for all architectures >> and operating systems on any platform. > I think this is fine, considering the options. Sitting down to produce an actual patch, i noticed that giving a few examples helps understanding, and there your idea comes in handy - not as a list of "the big ones", but just as "a few common examples". The list need not even be arbitrary; the criterion "common to FreeBSD, OpenBSD and NetBSD" gives us a very nice list. See below for my patch. OK to commit that to bsd.lv? I'm *NOT* going to commit that to OpenBSD; i will send a different patch for OpenBSD shortly. > Of course a remaining option is to make a mandoc_arch(7) manual, > but then we'd need mandoc_lib(7) too... but that's just messy. I don't like that either. We get no prize for the largest number of manuals. > I think a similar note should be put into the `Lb' documentation in > referring to libraries in lib.in, too, as it's not a fixed set. I'm undecided about that point right now, and it doesn't seem urgent: I feel comfortable with what we have now. Maybe it's not even important for the user. If the user wants to talk about .Lb foo, s/he will just put .Lb foo, and see what happens. On FreeBSD, that will probably be a system library (they have many, don't they), and OpenBSD will regard it as a custom library (unless it's c or util, well, kind of). That's fine, isn't it? Yours, Ingo Index: mdoc.7 =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v retrieving revision 1.212 diff -u -p -r1.212 mdoc.7 --- mdoc.7 27 Sep 2011 21:49:23 -0000 1.212 +++ mdoc.7 24 Oct 2011 22:14:55 -0000 @@ -1363,42 +1363,26 @@ or .Ar CON .Pq contributed manuals . .It Ar arch -This specifies a specific relevant architecture. -If -.Ar volume -is not provided, it may be used in its place, else it may be used -subsequent that. -It, too, is optional. -It must be one of -.Ar alpha , -.Ar amd64 , -.Ar amiga , -.Ar arc , -.Ar arm , -.Ar armish , -.Ar aviion , -.Ar hp300 , -.Ar hppa , -.Ar hppa64 , -.Ar i386 , -.Ar landisk , -.Ar loongson , -.Ar luna88k , -.Ar mac68k , -.Ar macppc , -.Ar mips64 , -.Ar mvme68k , -.Ar mvme88k , -.Ar mvmeppc , -.Ar pmax , -.Ar sgi , -.Ar socppc , -.Ar sparc , -.Ar sparc64 , -.Ar sun3 , -.Ar vax , +This specifies the machine architecture a manual page applies to, +for example +.Cm alpha , +.Cm amd64 , +.Cm i386 , or -.Ar zaurus . +.Cm sparc64 . +It can be provided either after or instead of the +.Ar volume . +Most manuals are machine-independent and don't use this argument at all. +The list of supported architectures varies by operating system. +For the full list of all architectures recognized by +.Xr mandoc 1 , +see the file +.Pa arch.in +in the source distribution. +Note that +.Xr mandoc 1 +can format manuals for all architectures and operating systems +on any platform. .El .Pp Examples: -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2011-10-24 22:32 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2011-10-16 15:06 fill gaps in arch.in and lib.in Ingo Schwarze [not found] ` <20111016155419.GC8820@harkle.home.gateway> 2011-10-16 16:10 ` Ingo Schwarze 2011-10-16 16:14 ` Kristaps Dzonsons 2011-10-16 16:42 ` Ingo Schwarze 2011-10-24 16:30 ` Kristaps Dzonsons 2011-10-24 22:25 ` Ingo Schwarze
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).