fill gaps in arch.in and lib.in

fill gaps in arch.in and lib.in

[Ingo Schwarze]

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

Re: fill gaps in arch.in and lib.in

[Ingo Schwarze]

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

Re: fill gaps in arch.in and lib.in

[Kristaps Dzonsons]

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

Re: fill gaps in arch.in and lib.in

[Ingo Schwarze]

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

Re: fill gaps in arch.in and lib.in

[Kristaps Dzonsons]

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

Re: fill gaps in arch.in and lib.in

[Ingo Schwarze]

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