Re: How do I get the man page for a package I haven't installed yet?

[Ingo Schwarze]

Hi,

Eric Furman wrote on Tue, Jun 23, 2020 at 07:12:33PM -0400:
> On Tue, Jun 23, 2020, at 2:20 PM, Theo de Raadt wrote:
>> Ottavio Caruso  wrote:

>>> Unless I've got it all wrong,  will only
>>> display man pages for programs and commands in base. Is there a way to
>>> display the man page for a package/port I haven't installed and/or
>>> downloaded yet? (This assumes I haven't downloaded the ports cvs
>>> tree).

>> Doing that would be very annoying and painful, and very few people
>> would want it.  It would also substantially degrade the clarity at
>> man.openbsd.org

> I think the best option is if the program you want to install has
> a web page would be to go there and ask them if they could
> put up the docs you want.

I'm not a fan of that advice.  Usually, it's not a good idea to go
huntiing for documentation on the web because you easily end up
with documentation for the wrong version.  Well, if you pay close
attention to which version you have and which version the documentation
is for, it may occasionally work - if whatever site you find reports
the version and reports it correctly.  It may suffice for a quick
first look to decide whether or not you want to seriously consider
using the software.

If you want to start studying the documentation in earnest, it may
be a better idea to just install the package, even if you don't
plan to run the software right away.  As opposed to systems like
Debian, installing a package you do not want to run is actually
safe on OpenBSD: OpenBSD will not automatically run things just
because you install them.

Yours,
  Ingo

Re: How do I get the man page for a package I haven't installed yet?

[Ingo Schwarze]

Hi Marc,

Marc Espie wrote on Fri, Jun 26, 2020 at 10:43:49PM +0200:
> On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:
>> Ottavio Caruso  wrote:

>>> Unless I've got it all wrong,  will only
>>> display man pages for programs and commands in base. Is there a way to
>>> display the man page for a package/port I haven't installed and/or
>>> downloaded yet? (This assumes I haven't downloaded the ports cvs
>>> tree).

>> Doing that would be very annoying and painful, and very few people
>> would want it.  It would also substantially degrade the clarity at
>> man.openbsd.org

Which means that *if* we ever do this, it needs to be a separate
manpath "ports", "ports-current" or something similar, which would
result in URIs like

  https://man.openbsd.org/ports-current/got.1

> Actually, it ought to be feasible to have the same mechanism in place for
> base  as a third party mechanism.
> 
> I don't think it would be that difficult to setup, this obviously ought to
> be separate from the main OpenBSD installation, as the quality of manpages
> from ports is often not up-to-par compared to base.
> 
> Both Ingo and naddy and I, we've been routinely passing all manpages from
> all packages through groff and mandoc and makewhatis to the point that
> over 99% of them would be clean for a usage similar to man.openbsd.org

Actually, you are mistaken here, i have never done that and i
wouldn't know how to do it.  All i did was look at ports setting
USE_GROFF, triage them, and improve mandoc(1) to handle them.
It is true that naddy helped a great deal with that.

That said, i have heard rumours that sthen@ can run things over all
manual pages in ports but i'm not quite sure, and i have no idea
how he does it.

If there is an easy way to get a tarball of all ports manual
pages (no matter whether for -current, -release, or both), putting
that up would be trivial and not cause significant additional work.
I'm simply not aware of an easy way to get that tarball.

Yours,
  Ingo

Re: How do I get the man page for a package I haven't installed yet?

[Eric Furman]

Let us say just for example I am running Mono on Windows OS.
If I need to look at docs would I go to Microsoft.com?
Of course I wouldn't. That would be silly. I would go to Mono's
website. So why would people think that all the ports docs should
be at OpenBSD.com?

Re: How do I get the man page for a package I haven't installed yet?

[Jordan Geoghegan]

On 2020-06-26 20:03, Theo de Raadt wrote:

Jordan Geoghegan  wrote:


On 2020-06-26 18:45, Theo de Raadt wrote:

Jordan Geoghegan  wrote:



On 2020-06-26 13:43, Marc Espie wrote:

On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:

Ottavio Caruso  wrote:


Hi,

Unless I've got it all wrong,  will only
display man pages for programs and commands in base. Is there a way to
display the man page for a package/port I haven't installed and/or
downloaded yet? (This assumes I haven't downloaded the ports cvs
tree).

Doing that would be very annoying and painful, and very few people
would want it.  It would also substantially degrade the clarity at
man.openbsd.org

Actually, it ought to be feasible to have the same mechanism in place for
base  as a third party mechanism.

I don't think it would be that difficult to setup, this obviously ought to
be separate from the main OpenBSD installation, as the quality of manpages
from ports is often not up-to-par compared to base.

Both Ingo and naddy and I, we've been routinely passing all manpages from
all packages through groff and mandoc and makewhatis to the point that
over 99% of them would be clean for a usage similar to man.openbsd.org


FreeBSD appears to offer manual pages from ports on their man page
website: https://www.freebsd.org/cgi/man.cgi

Not advocating for anything, just thought I'd point it out.

Completely irrelevant.


I thought it was relevant for folks looking for http access to ports
manpages, as the FreeBSD and OpenBSD ports trees overlap
significantly. I often use that site when I'm on a machine that
doesn't happen to have the particular package installed whose manpage
I want to view.

It is very easy for outsiders to ask a project to do more, MORE MORE
MORE, and not understand there are a limited number of people doing the
work.

So if this gets done, something else will not get done, or will get done
less well.

And it will be your fault.




I wasn't asking for anything, I was just trying to be helpful and share 
a resource I've personally found useful. I don't feel strongly about any 
of this, so consider the conversation over.


Regards,

Jordan

Re: How do I get the man page for a package I haven't installed yet?

[Theo de Raadt]

Jordan Geoghegan  wrote:

> On 2020-06-26 18:45, Theo de Raadt wrote:
> > Jordan Geoghegan  wrote:
> >
> >>
> >>
> >> On 2020-06-26 13:43, Marc Espie wrote:
> >>> On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:
>  Ottavio Caruso  wrote:
> 
> > Hi,
> >
> > Unless I've got it all wrong,  will only
> > display man pages for programs and commands in base. Is there a way to
> > display the man page for a package/port I haven't installed and/or
> > downloaded yet? (This assumes I haven't downloaded the ports cvs
> > tree).
>  Doing that would be very annoying and painful, and very few people
>  would want it.  It would also substantially degrade the clarity at
>  man.openbsd.org
> >>> Actually, it ought to be feasible to have the same mechanism in place for
> >>> base  as a third party mechanism.
> >>>
> >>> I don't think it would be that difficult to setup, this obviously ought to
> >>> be separate from the main OpenBSD installation, as the quality of manpages
> >>> from ports is often not up-to-par compared to base.
> >>>
> >>> Both Ingo and naddy and I, we've been routinely passing all manpages from
> >>> all packages through groff and mandoc and makewhatis to the point that
> >>> over 99% of them would be clean for a usage similar to man.openbsd.org
> >>>
> >> FreeBSD appears to offer manual pages from ports on their man page
> >> website: https://www.freebsd.org/cgi/man.cgi
> >>
> >> Not advocating for anything, just thought I'd point it out.
> > Completely irrelevant.
> >
> 
> I thought it was relevant for folks looking for http access to ports
> manpages, as the FreeBSD and OpenBSD ports trees overlap
> significantly. I often use that site when I'm on a machine that
> doesn't happen to have the particular package installed whose manpage
> I want to view.

It is very easy for outsiders to ask a project to do more, MORE MORE
MORE, and not understand there are a limited number of people doing the
work.

So if this gets done, something else will not get done, or will get done
less well.

And it will be your fault.

Re: How do I get the man page for a package I haven't installed yet?

[Jordan Geoghegan]

On 2020-06-26 18:45, Theo de Raadt wrote:

Jordan Geoghegan  wrote:




On 2020-06-26 13:43, Marc Espie wrote:

On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:

Ottavio Caruso  wrote:


Hi,

Unless I've got it all wrong,  will only
display man pages for programs and commands in base. Is there a way to
display the man page for a package/port I haven't installed and/or
downloaded yet? (This assumes I haven't downloaded the ports cvs
tree).

Doing that would be very annoying and painful, and very few people
would want it.  It would also substantially degrade the clarity at
man.openbsd.org

Actually, it ought to be feasible to have the same mechanism in place for
base  as a third party mechanism.

I don't think it would be that difficult to setup, this obviously ought to
be separate from the main OpenBSD installation, as the quality of manpages
from ports is often not up-to-par compared to base.

Both Ingo and naddy and I, we've been routinely passing all manpages from
all packages through groff and mandoc and makewhatis to the point that
over 99% of them would be clean for a usage similar to man.openbsd.org


FreeBSD appears to offer manual pages from ports on their man page
website: https://www.freebsd.org/cgi/man.cgi

Not advocating for anything, just thought I'd point it out.

Completely irrelevant.



I thought it was relevant for folks looking for http access to ports 
manpages, as the FreeBSD and OpenBSD ports trees overlap significantly. 
I often use that site when I'm on a machine that doesn't happen to have 
the particular package installed whose manpage I want to view.


Regards,

Jordan

Re: How do I get the man page for a package I haven't installed yet?

[Theo de Raadt]

Jordan Geoghegan  wrote:

> 
> 
> 
> On 2020-06-26 13:43, Marc Espie wrote:
> > On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:
> >> Ottavio Caruso  wrote:
> >>
> >>> Hi,
> >>>
> >>> Unless I've got it all wrong,  will only
> >>> display man pages for programs and commands in base. Is there a way to
> >>> display the man page for a package/port I haven't installed and/or
> >>> downloaded yet? (This assumes I haven't downloaded the ports cvs
> >>> tree).
> >> Doing that would be very annoying and painful, and very few people
> >> would want it.  It would also substantially degrade the clarity at
> >> man.openbsd.org
> > Actually, it ought to be feasible to have the same mechanism in place for
> > base  as a third party mechanism.
> >
> > I don't think it would be that difficult to setup, this obviously ought to
> > be separate from the main OpenBSD installation, as the quality of manpages
> > from ports is often not up-to-par compared to base.
> >
> > Both Ingo and naddy and I, we've been routinely passing all manpages from
> > all packages through groff and mandoc and makewhatis to the point that
> > over 99% of them would be clean for a usage similar to man.openbsd.org
> >
> 
> FreeBSD appears to offer manual pages from ports on their man page
> website: https://www.freebsd.org/cgi/man.cgi
> 
> Not advocating for anything, just thought I'd point it out.

Completely irrelevant.

Re: How do I get the man page for a package I haven't installed yet?

[Jordan Geoghegan]

On 2020-06-26 13:43, Marc Espie wrote:

On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:

Ottavio Caruso  wrote:


Hi,

Unless I've got it all wrong,  will only
display man pages for programs and commands in base. Is there a way to
display the man page for a package/port I haven't installed and/or
downloaded yet? (This assumes I haven't downloaded the ports cvs
tree).

Doing that would be very annoying and painful, and very few people
would want it.  It would also substantially degrade the clarity at
man.openbsd.org

Actually, it ought to be feasible to have the same mechanism in place for
base  as a third party mechanism.

I don't think it would be that difficult to setup, this obviously ought to
be separate from the main OpenBSD installation, as the quality of manpages
from ports is often not up-to-par compared to base.

Both Ingo and naddy and I, we've been routinely passing all manpages from
all packages through groff and mandoc and makewhatis to the point that
over 99% of them would be clean for a usage similar to man.openbsd.org



FreeBSD appears to offer manual pages from ports on their man page 
website: https://www.freebsd.org/cgi/man.cgi


Not advocating for anything, just thought I'd point it out.

Re: How do I get the man page for a package I haven't installed yet?

[Marc Espie]

On Tue, Jun 23, 2020 at 12:20:35PM -0600, Theo de Raadt wrote:
> Ottavio Caruso  wrote:
> 
> > Hi,
> > 
> > Unless I've got it all wrong,  will only
> > display man pages for programs and commands in base. Is there a way to
> > display the man page for a package/port I haven't installed and/or
> > downloaded yet? (This assumes I haven't downloaded the ports cvs
> > tree).
> 
> Doing that would be very annoying and painful, and very few people
> would want it.  It would also substantially degrade the clarity at
> man.openbsd.org

Actually, it ought to be feasible to have the same mechanism in place for
base  as a third party mechanism.

I don't think it would be that difficult to setup, this obviously ought to
be separate from the main OpenBSD installation, as the quality of manpages
from ports is often not up-to-par compared to base.

Both Ingo and naddy and I, we've been routinely passing all manpages from
all packages through groff and mandoc and makewhatis to the point that
over 99% of them would be clean for a usage similar to man.openbsd.org

Re: How do I get the man page for a package I haven't installed yet?

[Eric Furman]

On Tue, Jun 23, 2020, at 2:20 PM, Theo de Raadt wrote:
> Ottavio Caruso  wrote:
> 
> > Hi,
> > 
> > Unless I've got it all wrong,  will only
> > display man pages for programs and commands in base. Is there a way to
> > display the man page for a package/port I haven't installed and/or
> > downloaded yet? (This assumes I haven't downloaded the ports cvs
> > tree).
> 
> Doing that would be very annoying and painful, and very few people
> would want it.  It would also substantially degrade the clarity at
> man.openbsd.org

I think the best option is if the program you want to install has
a web page would be to go there and ask them if they could
put up the docs you want.

How do I get the man page for a package I haven't installed yet?

[Ottavio Caruso]

Hi,

Unless I've got it all wrong,  will only
display man pages for programs and commands in base. Is there a way to
display the man page for a package/port I haven't installed and/or
downloaded yet? (This assumes I haven't downloaded the ports cvs
tree).

Thanks

-- 
Ottavio Caruso

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?

Re: How do I get the man page for a package I haven't installed yet?

[Theo de Raadt]

Ottavio Caruso  wrote:

> Hi,
> 
> Unless I've got it all wrong,  will only
> display man pages for programs and commands in base. Is there a way to
> display the man page for a package/port I haven't installed and/or
> downloaded yet? (This assumes I haven't downloaded the ports cvs
> tree).

Doing that would be very annoying and painful, and very few people
would want it.  It would also substantially degrade the clarity at
man.openbsd.org