Re: [Groff] GNU troff in OpenBSD

[Ingo Schwarze]

Hi Werner,

Werner LEMBERG wrote on Mon, Oct 17, 2011 at 08:06:13AM +0200:
> Ingo Schwarze wrote:

>> The following works for our special purposes, seems less intrusive,
>> and allows to drop the fiddling with env.cpp.
>> 
>> Do you agree that's an improvement?

> It's an improvement, yes.  Please document this within OpenBSD...

>> +.\" Disable adjustment by default,
>> +.\" such that manuals look similar with groff and mandoc(1).
>> +.do ad l
>> +.do de ad
>> +..

> No need for `do' if you work with two-letter commands, BTW.

Thank you for your feedback!

I'm planning to use OpenBSD's new package README feature to tell the
users about the changes with respect to the official distribution.
I think that's better than patching the official manuals.
Changes in the manuals could easily be overlooked, or maybe even
misread as upstream changes.

So, when the user installs groff from packages or ports, the
following message will be displayed:

 $ sudo pkg_add groff
groff-1.21p6: ok
Look in /usr/local/share/doc/pkg-readmes for extra documentation.

And in /usr/local/share/doc/pkg-readmes/groff-1.21p6,
a text similar to the one shown below will be available.

Yours,
  Ingo



 $ cat /usr/local/share/doc/pkg-readmes/groff-1.21p6

+-----------------------------------------------------------------------
| Running groff-1.21p6 on OpenBSD
+-----------------------------------------------------------------------

Even though roff is a general-purpose typesetting system, the OpenBSD
groff port is focussed on formatting ports(5) manuals that mandoc(1)
is unable to handle.  To make groff output as similar as possible to
mandoc output, the following two groff features have been disabled by
default: adjustment of text to the right margin and hyphenation.

If you want to use groff for serious typesetting work and need these
features, please edit the respective paragraphs in the file

  /usr/local/share/groff/1.21/tmac/troffrc

to read like this:

.do hpf hyphen.us
.do hpfa hyphenex.us

.\"ad l
.\"de ad
.\".


To suit the taste of OpenBSD developers, two mdoc(7) formatting
details have been changed with respect to the upstream distribution:

 * Title lines use an n-dash, not an m-dash between the manual page
   name and the manual page description.

 * The .Pa macro always produces emphasized text,
   even in the FILES section.

To allow automated output comparisons with mandoc(1), the bullet
character \(bu has been changed to just "o" instead of a "+"
superimposed on top of an "o".