trying to improve mandoc Solaris support

[Joerg Schilling via buildfarm]

Ingo Schwarze <schwarze at usta.de> wrote:

> According to Cynthia, three noteworthy versions existed:
>
>  * mdoc(7) version 1 was never checked into version control, never
>    published, and the source code is probably lost.  It was what
>    Cynthia used when starting the work.
>
>  * mdoc(7) version 2 is still available here:
>    http://svnweb.freebsd.org/csrg/share/tmac/tmac.doc.old
>    That version was short-lived:  It was only contained
>    in 4.3BSD-Reno and 4.3BSD-Net/2, but in Reno, only a small
>    number of manuals was converted to mdoc(7), most were still
>    shipped in the old man(7) format, and in Net/2, conversion
>    to version 3 had already started.
>    
>  * mdoc(7) version 3 is available here:
>    http://svnweb.freebsd.org/csrg/share/tmac/doc
>    (and the doc-* files in the same directory)
>    That's the version used in all variants of 4.4BSD,
>    and the only one people usually have in mind when talking
>    about "mdoc(7)" today.

OK, I am using a file based on:

	CSRG/CSRG_Archive_3/4.4/usr/share/tmac/tmac.doc

I have no idea how this is related to the svn conversion.

> > If there are improvements, please keep me informed.
>
> You should probably just follow
>
>   https://github.com/n-t-roff/heirloom-doctools/

I would need to download this as the web interface is not nice to compare such 
things.

> Carsten also announces releases on <groff at gnu.org>.
>
> I'm not directly involved with Heirloom troff development,
> so i'm not the ideal person to keep people informed about it.

So is the development of this decoupled from Gunnar Ritter?


> > Are there *BSD man pages that go beyond the official 6 argument
> > limit for troff macros?
>
> Yes, we dropped that restriction in OpenBSD about four years ago,
> and i doubt that FreeBSD and NetBSD still abide by it.
>
> > From my interpretation, using such features is not a good idea if you 
> > intend to create portable man pages.
>
> Well, portable to what?  Historic systems?

I create portable software and I assume that my software also works on HP-UX 
and AIX. 

> > For this reason I decided not to enhance the Solaris man macros
> > to support more than 6 arguments, just to be sure to 
> > detect problems early if I write or enhance man pages.
>
> I'm not sure that's a wise choice.  Probably, the only effect is
> that Solaris may be the only modern system out there that has
> problems rendering modern manuals (admittedly, i didn't try, but
> that's what i would expect).  Maybe, when i'm bored, i might
> copy the OpenBSD manuals to the OpenCSW cluster and have a look...

I am sure there are other systems with this restriction.

> Performance very much depends on the language (mdoc(7) vs. man(7),
> and possibly tbl(7) and eqn(7)) and the size of the page in
> question, so giving a single number does not tell me very much.
> In general, performance differs more for mdoc(7) than for man(7)
> and more for smaller pages than for larger ones.

As I fixed the Solaris man pages (Sun did destroy them when converting them to 
sgxml for a Framemaker plugin and later back to troff. You can have a look at 
the current state of the man pages in the Mercurial of SchilliX-ON and HTML 
converted at:

	http://schillix.sourceforge.net/man/

As the conversion could do bad thingd and as (unlike illumos) I have quality 
standards for the man pages, I do a 100% check for all man pages after each 
conversion step. I used a similar script to roff all Solaris man pages using 
troff, groff and mandoc and I compared the time. 


> [...]
> > My impression with the mdoc() macro set is that it mainly tries
> > to provide new macros for use cases that work with classical
> > man(5) macros if you know that there is \c to innterupt line
> > processing with [nt]roff.
>
> Not at all.  The point of mdoc(7) is semantic markup, while man(7)
> is purely presentational markup.  So the two languages serve
> completely different purposes.

Where/how does this help?

> [...]
> > I did not yet check the quality of Heirloom troff.  I know however
> > that there is not much maintenance for all the projects in Heirloom
> > that I checked before.
>
> Heirloom troff is now maintained seperately from the rest of the
> Heirloom tools.

Is there a place where I can read something about the background for this 
project?


> > BTW: One reason is line formatting.  I prefer full justification
> > before left aligned text.
>
> That's indeed a matter of taste.  The vast majority of OpenBSD
> developers prefer flush-left, and i don't remeber hearing complaints
> about it from FreeBSD, NetBSD, DragonFly, illumos or any of the
> Linux ports either.  Implementing .ad would not be that difficult,
> but demand is tiny, so i'm treating it as a low-priority task.

Then it would look like classical man pages. 

Jörg

-- 
 EMail:joerg at schily.net                    (home) Jörg Schilling D-13353 Berlin
       joerg.schilling at fokus.fraunhofer.de (work) Blog: http://schily.blogspot.com/
 URL:  http://cdrecord.org/private/ http://sourceforge.net/projects/schilytools/files/'