On Jun 29 15:08:12, schwa...@usta.de wrote:
> Hi Jan,
>
> Jan Stary wrote on Sat, Jun 29, 2013 at 02:28:55PM +0200:
>
> > Certain ports require groff because that's what
> > their manpages are written for.
>
> Manuals specifically written for groff (as opposed to for roff in
> general) probably exist, but i don't think that's the majority of
> manuals requiring groff. Rather, i'd guess that most manuals
> requiring groff in OpenBSD ports use low-level roff formatting (in
> addition to man(7) macros) that is supported by most roff
> implementations, not just by groff.
Yes; where I said "manpages for groff",
I should have said "the legacy manpages".
> Admittedly, i didn't really check the above.
>
> But note that manuals written specifically for groff
> would hardly be usable e.g. on Solaris clones which typically
> do not inlude groff but older roff implementations.
>
> > If I understand
> > it correctly, the original manpages get preformated
> > with groff, installed into the .../cat/ directotries,
> > and that's what the user sees eventually.
>
> Yes, that's what USE_GROFF does, see bsd.port.mk(5).
>
> > I haven't found the time yet to look into the internals
> > of the mdoc(7) vs man(7) markup, but would it make
> > sense to try to slightly rewrite the original
> > manpages to get rid of groff?
>
> In the ports tree at large: No.
> That would be a gigantic make-work project,
> and lots of the work would have to be redone
> for each update of each affected port.
>
> That's completely unrealistic.
>
> Also note that the mdoc(7) and man(7) languages are completely
> distinct, they do not have a single common macro. Well, roff(7)
> requests can be used in both, but that's bad style in the first
> place.
>
> So, rewriting man(7) to mdoc(7) usually requires to change every
> single macro, and it usually requires adding several macros to
> the source code. It's more like rewriting the manual, not just
> like sprinkling a few changes.
Hm, that's what I was afraid of.
> In one single port, provided that you cooperate closely with
> upstream, they like the idea, and you know what you are doing?
> Yes.
The example I originally had in mind was mail/procmail.
It comes with
# ls -1 /usr/ports/pobj/procmail-3.22/procmail-3.22/man/
Makefile
Makefile.0
README
formail.man
lockfile.man
mansed
procmail.man
procmailex.man
procmailrc.man
procmailsc.man
and says
Please note that the *.man files in this directory still need to be
converted into their *.1 and *.5 counterparts. You can convert them
by typing "make" in this directory or in the directory above.
The man pages *.1 and *.5 can then be displayed as readable plain text
by typing something like this:
nroff -man procmail.1
or they can be moved to man directories in your MANPATH
to be be viewed with the normal man command.
Indeed, the procmail build produces a procmail.1 and others,
and thats what gets preprocessed and installed with the package.
I suppose the resulting *.1 is a man(7) source.
Could you please enlighten me historically on
what the *.man format is? The translation happens
with Guenther's ./mansed, which seems to be an
ad hoc sed translation of one set of macros into another.
> However, if upstream wants to provide manuals for Solaris clones,
> they will need to do automatic mdoc(7) to man(7) conversions
> using mandoc -mdoc -Tman in the tarball build system, like
> portable sudo(1) does. That works quite well now, but requires
> mandoc in the tarball build system, so some upstream projects
> may not like the idea.
Well, the upstream of procmail is Philip A. Guenther.
So, as an example, what would it take to convert the
procmail documentation to mdoc(7), while keeping the
documentation usable for systems other that OpenBSD?
> > Is that generally
> > possible? Is an mdoc(7) manpage, when written
> > with compatibility in mind, acceptable for upstream
> > that originaly wrote the manpage for groff?
>
> That depends on the taste of the upstream developers.
> I think moving from man(7) to mdoc(7) and using -Tman
> makes manuals better, but some upstream projects will
> certainly disagree - or simply not care at all.
Reading
http://www.undeadly.org/cgi?action=article&sid=20100604082319&mode=expanded
specifically Kristaps'
Lastly, if one's manuals are in -man format, for gods sakes
re-write them in -mdoc format!
is what got me into this. I will try to find a small
man(7) page of a GROFF-dependent port I care about
and try to persuade upstream to let me rewtite into mdoc(7)
and see how that goes.
Or is there something in base still not converted to mdoc?
Would you please suggest a small bit I could learn this on?
