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

[Ingo Schwarze <schwarze@usta.de>]

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