Re: How to print nicely formatted man pages?

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Sijmen J. Mulder
> Op 7 feb. 2019 om 08:29 heeft Anne Wainwright <[hidden email]> het volgende geschreven:
>
> I can print out nicely formatted man pages in linux, thus:
>
> $ man -t ls | lpr -P hp_laserjet
>
> But find that the -t option is not present in bsd.
>
> Have really dug around but can find no hints, where should I be looking?

man supports mandoc’s -T option, e.g.:

man -T ps | ...

There’s a little note about it at the end of the option list in man’s man page. See mandoc’s man page for the formats and such.

Cheers,
Sijmen

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Peter N. M. Hansteen-3
On Thu, Feb 07, 2019 at 09:29:39AM +0200, Anne Wainwright wrote:
> I can print out nicely formatted man pages in linux, thus:
>
> $ man -t ls | lpr -P hp_laserjet
>
> But find that the -t option is not present in bsd.
>
> Have really dug around but can find no hints, where should I be looking?

I would say what you are probably looking for is mandoc (man mandoc or
http://man.openbsd.org/mandoc), which supports a variety of output formats.

- Peter

--
Peter N. M. Hansteen, member of the first RFC 1149 implementation team
http://bsdly.blogspot.com/ http://www.bsdly.net/ http://www.nuug.no/
"Remember to set the evil bit on all malicious network traffic"
delilah spamd[29949]: 85.152.224.147: disconnected after 42673 seconds.

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Ingo Schwarze
In reply to this post by Sijmen J. Mulder
Hi,

Sijmen J. Mulder wrote on Thu, Feb 07, 2019 at 09:50:47AM +0100:
> Op 7 feb. 2019 om 08:29 heeft Anne Wainwright het volgende geschreven:

>> I can print out nicely formatted man pages in linux, thus:
>>
>> $ man -t ls | lpr -P hp_laserjet
>>
>> But find that the -t option is not present in bsd.
>>
>> Have really dug around but can find no hints, where should I be looking?

> man supports mandoc's -T option, e.g.:
>
> man -T ps | ...

That is the correct answer.

But please, if you can, always provide complete, working, tested
command invocations to users, in this case:

  $ man -T ps ls > ls.ps

to generate a PostScript file on disk or

  $ man -T ps ls | lpr

to directly send the same PostScript code to the default printer.

That practice helps to avoid misunderstandings and to promote
good idioms.

> There's a little note about it at the end of the option list in
> man's man page.  See mandoc's man page for the formats and such.

Exactly.  The reason for doing it like that was to keep the man(1)
manual page simple because new users have to read that quite early
when they are not yet experienced.  It would be of dubious benefit
to put lots of rarely-used non-standard options into the man(1)
manual.  Besides, duplicate information is also a problem - both
for maintenance and because it forces readers to scan and compare
two (identical? similar? or subtly different?) versions.

As to why we have mo -t option, see

  http://mandoc.bsd.lv/man/man.options.1.html
  http://mandoc.bsd.lv/man/man.options.1.html#t

Even though it is similar to -T ps in most man(1) implementations,
it has ambiguous meanings in the wider program family, in particular:

 - preprocess with tbl(7) in groff
 - test = check manual pages in the hierarchy with mandb
 - test = check files for problems related to mandoc.db(5) in makewhatis

So i decided it is best to not implement an alias -t, also because
every alias makes the documentation longer, and it is best to get
used to the -T ps option which needs to be supported anyway.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Ingo Schwarze
In reply to this post by Peter N. M. Hansteen-3
Hi Peter,

Peter N. M. Hansteen wrote on Thu, Feb 07, 2019 at 10:26:03AM +0100:
> On Thu, Feb 07, 2019 at 09:29:39AM +0200, Anne Wainwright wrote:

>> I can print out nicely formatted man pages in linux, thus:
>>
>> $ man -t ls | lpr -P hp_laserjet
>>
>> But find that the -t option is not present in bsd.
>>
>> Have really dug around but can find no hints, where should I be looking?

> I would say what you are probably looking for is mandoc (man mandoc or
> http://man.openbsd.org/mandoc), which supports a variety of output formats.

That answer is mostly correct in so far as the mandoc(1) manual page
indeed documents the -T option and PostScript output mode, but it is
also slightly misleading for the following reason:

If there is anything you can do with apropos(1), whatis(1), or mandoc(1),
then you can do exactly the same thing with man(1):

  apropos ...  ==  man -k  ...
  whatis  ...  ==  man -f  ...
  mandoc  ...  ==  man -lc ...

where "..." stands for additional options and arguments.

So "mandoc" no longer has significance as a separate program with
distinct options and/or functionality: it is just the same program
as man(1), except for having -l and -c active by default.

Of course the name "mandoc" is still significant for the (portable)
software package implementing man(1), apropos(1), whatis(1), help(1),
mandoc(1), makewhatis(8), and man.cgi(8) in OpenBSD style.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Ingo Schwarze
In reply to this post by Sijmen J. Mulder
Hi Anne,

Anne Wainwright wrote on Thu, Feb 07, 2019 at 05:54:04PM +0200:

> I have now got well-formatted pages chugging out from the printer.

Good.  :-)

> I did use the example at the end of the mandoc man which outputs .ps
> files. But I did not succeed in persuading lp to print them. Thus:
>
> $ lp lpadmin.ps
> lp: no file in print request
>
> so not sure what the issue is there, but what I have is what I need.

A command called "lp" simply doesn't exist in the OpenBSD base system:

   $ man lp
  man: No entry for lp in the manual.
   $ which lp
  which: lp: Command not found.

Just use lpr(1) = /usr/bin/lpr.

   $ pkglocate bin/lp | grep 'lp$'
  cups-2.2.10p0:print/cups,-main:/usr/local/bin/lp

I'd advise against using cups when you can avoid it.
It is a behemoth that is extremely poorly designed,
and the documentation of cups is of terrible quality.

You are no doubt in for no end of surprises if you attempt
to use cups.  Admittedly, with some low-quality printers,
using it may look like an easy workaround for other problems.

But if your printer understands PostScript, you should be just
fine without cups.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Sijmen J. Mulder
In reply to this post by Ingo Schwarze
Op do feb 7 2019, om 14:33 schreef Ingo Schwarze:
> But please, if you can, always provide complete, working, tested
> command invocations to users, in this case:

Apologies - I was on mobile which but that's no excuse.

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Ingo Schwarze
Hi,

Sijmen J. Mulder wrote on Thu, Feb 07, 2019 at 05:41:57PM +0100:
> Op do feb 7 2019, om 14:33 schreef Ingo Schwarze:

>> But please, if you can, always provide complete, working, tested
>> command invocations to users, in this case:

> Apologies - I was on mobile which but that's no excuse.

No need to apologize - a timely and correct answer is of course
better than no answer.  I didn't intend to discourage that.  :)

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Rajneesh Shetty-3
In reply to this post by Sijmen J. Mulder
www.dqindia.com/importance-patents-iot-enabled-devices/

Rajneesh N. Shetty

--------------------------------------------
On Thu, 7/2/19, Peter N. M. Hansteen <[hidden email]> wrote:

 Subject: Re: How to print nicely formatted man pages?
 To: [hidden email]
 Received: Thursday, 7 February, 2019, 8:26 PM
 
 On Thu, Feb 07, 2019 at 09:29:39AM +0200, Anne
 Wainwright wrote:
 > I can print out nicely
 formatted man pages in linux, thus:
 >
 > $ man -t ls | lpr -P hp_laserjet
 >
 > But find that the -t
 option is not present in bsd.
 >
 > Have really dug around but can find no
 hints, where should I be looking?
 
 I would say what you are probably looking for
 is mandoc (man mandoc or
 http://man.openbsd.org/mandoc), which
 supports a variety of output formats.
 
 - Peter
 
 --
 Peter N. M. Hansteen, member of the first RFC
 1149 implementation team
 http://bsdly.blogspot.com/ http://www.bsdly.net/ http://www.nuug.no/
 "Remember to set the evil bit on all
 malicious network traffic"
 delilah
 spamd[29949]: 85.152.224.147: disconnected after 42673
 seconds.
 
 
 -----Inline Attachment Follows-----

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Beto-3
In reply to this post by Sijmen J. Mulder
Hi try

man man | col -b > man.txt

br

El jue., 7 de feb. de 2019 a la(s) 11:03, Anne Wainwright (
[hidden email]) escribió:

> On Thu, Feb 07, 2019 at 09:29:39AM +0200, Anne Wainwright wrote:
> > Hi,
> >
> > I can print out nicely formatted man pages in linux, thus:
> >
> > $ man -t ls | lpr -P hp_laserjet
> >
> > But find that the -t option is not present in bsd.
> >
> > Have really dug around but can find no hints, where should I be looking?
> >
> > thanks in advance
> > Ian
> >
> Thankyou, Sijmen & Ingo,
>
> I have now got well-formatted pages chugging out from the printer.
>
> I did use the example at the end of the mandoc man which outputs .ps
> files. But I did not succeed in persuading lp to print them. Thus:
>
> $ lp lpadmin.ps
> lp: no file in print request
>
> so not sure what the issue is there, but what I have is what I need.
>
> best
> Ian
>
>
Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Ingo Schwarze
Hi Beto,

Beto wrote on Fri, Feb 08, 2019 at 07:45:50AM -0500:

> man man | col -b > man.txt

This is bad advice in the present context.
Look at the Subject: line.
Anne asked for "nicely formatted" printing.

Your solution would be adequate if the question
has been about "minimally formatted", though;
but it is locale-dependent.  The above command
generates UTF-8 output if LC_CTYPE is set to UTF-8
and ASCII output otherwise.  So whatever facility
is then used for printing needs to take the
encoding into account, whereas the solutions
with -T ps shown earlier always work in the same
way, ignoring the locale.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Stephen Gregoratto
In reply to this post by Sijmen J. Mulder
In my opinion I find the PostScript/PDF output from groff to be better
than mandoc's, sorry Ingo :(. The font size and line spacing makes a
better print, which makes sense considering that groff is a typesetting
suite. The catch is that groff doesn't detect if eqn(1) or tbl(1) needs
to be run for the man page, while mandoc does. You would need to use
grog(1) for that.

Here are some example pdf's for the 6.4 version of man(1):

https://www.sgregoratto.me/paste/man-groff.1.pdf
  $ groff -mandoc -T pdf /usr/share/man/man1/man.1
  alternatively...
  $ grog -T pdf --run /usr/share/man/man1/man.1
https://www.sgregoratto.me/paste/man-mandoc.1.pdf
  $ mandoc -T pdf /usr/share/man/man1/man.1
  alternatively...
  $ man -T pdf 1 man

You should replace 'pdf' with 'ps' if you are using a PostScript
printer. It's up to you to decide which one looks better.

--
Stephen Gregoratto

Reply | Threaded
Open this post in threaded view
|

Re: How to print nicely formatted man pages?

Ingo Schwarze
Hi,

Stephen Gregoratto wrote on Sat, Feb 09, 2019 at 10:41:17AM +1100:

> In my opinion I find the PostScript/PDF output from groff to be
> better than mandoc's, sorry Ingo :(.

Absolutely, that is exactly what i always say.

> The font size and line spacing makes a better print, which makes
> sense considering that groff is a typesetting suite.

There are lots of aspects in which groff(1) PostScript and PDF
output - i.e., output from a real typesetting system - is better
than mandoc(1)'s.

> The catch is that groff doesn't detect if eqn(1) or tbl(1) needs
> to be run for the man page, while mandoc does.

Yes.  One goal of mandoc(1) -T ps/pdf is to make calling it easy,
without having to worry about *any* options, such that it can be
used casually (safely and reliably) to get a quick printout.

> You would need to use grog(1) for that.

I strongly advise against using grog(1).  It is a disgusting kludge
written by an extremely careless programmer (Bernd Warken).  Since
Bernd is no longer able to do any programming at all AFAIK, it is
now also effectively unmaintained and subject to bitrot on top of
the poor quality it has in the first place.

At one point, i considered simply deleting grog(1) from the OpenBSD
textproc/groff package - but then again, OpenBSD packages should
not be prejudiced, and since grog(1) is still distributed upstream,
it is still contained in the groff package.  But that doesn't mean
anyone should run it.

If you want to use groff, use options like "-k", "-e" or "-t" to
the groff(1) program as needed or construct pipelines the traditional
way.  Even that is clearly more fragile and riskier with untrusted
input than running mandoc, but not quite as bad as grog(1).

> Here are some example pdf's for the 6.4 version of man(1):
> https://www.sgregoratto.me/paste/man-groff.1.pdf
> https://www.sgregoratto.me/paste/man-mandoc.1.pdf
> It's up to you to decide which one looks better.

It is not just a matter of personal taste.  The groff(1) output is
objectively better.  For example, these two URIs show that mandoc
fails to do adjustment (look at the right margin in the ENVIRONMENT
section) and fails to use constant-width font where it should (look
at the displays in the EXAMPLES section).  All the same, it is
convenient for just getting a quick printout.

Yours,
  Ingo