How to handle different sections with new man.conf?

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

How to handle different sections with new man.conf?

Andy Bradford-21
Hello,

Using OpenBSD 5.8-stable.

I used to have the following in /etc/man.conf:

tcl85           /usr/local/lib/tcl/tcl8.5/man/
tcl86           /usr/local/lib/tcl/tcl8.6/man/

Which  made it  easy to  view  one or  the  other by  using the  section
argument:

man tcl85 Tcl
man tcl86 Tcl

man(1) still appears to be documented to have this functionality:

     man [-acfhklw] [-C file] [-I os=name] [-K encoding] [-M path] [-m path]
         [-O option=value] [-S subsection] [-s section] [-T output] [-W level]
         [section] name ...
         ^^^^^^^^^

But I see no  way of expressing it in the new  man.conf or addressing it
in the  command line.  Here is what  I have added  according to  the new
man.conf(5):

manpath /usr/local/lib/tcl/tcl8.5/man
manpath /usr/local/lib/tcl/tcl8.6/man

But I don't see how to  use [section] anymore. man(1) does mention using
[-s section] with n  as the section, but that only  seems to display the
first match of tcl8.5 and does  not allow further granularity (as far as
I can tell).

Have I missed something in the man pages, or what am I doing wrong?

Thanks,

Andy
--
TAI64 timestamp: 40000000576f0095

Reply | Threaded
Open this post in threaded view
|

Re: How to handle different sections with new man.conf?

Jason McIntyre-2
On Sat, Jun 25, 2016 at 04:06:41PM -0600, Andy Bradford wrote:

> Hello,
>
> Using OpenBSD 5.8-stable.
>
> I used to have the following in /etc/man.conf:
>
> tcl85           /usr/local/lib/tcl/tcl8.5/man/
> tcl86           /usr/local/lib/tcl/tcl8.6/man/
>
> Which  made it  easy to  view  one or  the  other by  using the  section
> argument:
>
> man tcl85 Tcl
> man tcl86 Tcl
>
> man(1) still appears to be documented to have this functionality:
>
>      man [-acfhklw] [-C file] [-I os=name] [-K encoding] [-M path] [-m path]
>          [-O option=value] [-S subsection] [-s section] [-T output] [-W level]
>          [section] name ...
>          ^^^^^^^^^
>
> But I see no  way of expressing it in the new  man.conf or addressing it
> in the  command line.  Here is what  I have added  according to  the new
> man.conf(5):
>
> manpath /usr/local/lib/tcl/tcl8.5/man
> manpath /usr/local/lib/tcl/tcl8.6/man
>
> But I don't see how to  use [section] anymore. man(1) does mention using
> [-s section] with n  as the section, but that only  seems to display the
> first match of tcl8.5 and does  not allow further granularity (as far as
> I can tell).
>
> Have I missed something in the man pages, or what am I doing wrong?
>
> Thanks,
>
> Andy

hi.

i don;t think it's currently possible to do exactly what you propose. i
think ingo stripped man.conf pretty bare.

the workarounds would be:

    - have multiple conf files and use man -C to get the one you want
    - use man -m on the command line (or aliases) to get what you want

i think man(1) is currently wrong regarding the section values in -s
(i'll look into that).

jmc

Reply | Threaded
Open this post in threaded view
|

Re: How to handle different sections with new man.conf?

lists-2
> > Hello,
> >
> > Using OpenBSD 5.8-stable.
> >
> > I used to have the following in /etc/man.conf:
> >
> > tcl85           /usr/local/lib/tcl/tcl8.5/man/
> > tcl86           /usr/local/lib/tcl/tcl8.6/man/
> >
> > Which  made it  easy to  view  one or  the  other by  using the  section
> > argument:
> >
> > man tcl85 Tcl
> > man tcl86 Tcl
> >
> > man(1) still appears to be documented to have this functionality:
> >
> >      man [-acfhklw] [-C file] [-I os=name] [-K encoding] [-M path] [-m path]
> >          [-O option=value] [-S subsection] [-s section] [-T output] [-W level]
> >          [section] name ...
> >          ^^^^^^^^^
> >
> > But I see no  way of expressing it in the new  man.conf or addressing it
> > in the  command line.  Here is what  I have added  according to  the new
> > man.conf(5):
> >
> > manpath /usr/local/lib/tcl/tcl8.5/man
> > manpath /usr/local/lib/tcl/tcl8.6/man
> >
> > But I don't see how to  use [section] anymore. man(1) does mention using
> > [-s section] with n  as the section, but that only  seems to display the
> > first match of tcl8.5 and does  not allow further granularity (as far as
> > I can tell).
> >
> > Have I missed something in the man pages, or what am I doing wrong?
> >
> > Thanks,
> >
> > Andy  
>
> hi.
>
> i don;t think it's currently possible to do exactly what you propose. i
> think ingo stripped man.conf pretty bare.
>
> the workarounds would be:
>
>     - have multiple conf files and use man -C to get the one you want
>     - use man -m on the command line (or aliases) to get what you want
>
> i think man(1) is currently wrong regarding the section values in -s
> (i'll look into that).
>
> jmc

The multiple configuration files is one working approach to multiple
work directory invocation, and these can coexist.  Then more over so,
there must be a way to call tcl85 and tcl86 something else than both
"Tcl" right?  Meaning maybe also seek ways to reconcile these in Tcl
land & potentially other multiple versions environments.  W/ regards,
please excuse me, if this is out of line or just plain inappropriate.

Reply | Threaded
Open this post in threaded view
|

Re: How to handle different sections with new man.conf?

Ingo Schwarze
Hi Andy,

[hidden email] wrote on Sun, Jun 26, 2016 at 01:50:34PM +0300:
> Jason McIntyre wrote:
>> Andy Bradford wrote:

>>> Using OpenBSD 5.8-stable.
>>>
>>> I used to have the following in /etc/man.conf:
>>>
>>> tcl85           /usr/local/lib/tcl/tcl8.5/man/
>>> tcl86           /usr/local/lib/tcl/tcl8.6/man/
>>>
>>> Which made it easy to view one or the other by using the section
>>> argument:
>>>
>>> man tcl85 Tcl
>>> man tcl86 Tcl
>>>
>>> man(1) still appears to be documented to have this functionality:
>>>
>>>  man [-acfhklw] [-C file] [-I os=name] [-K encoding] [-M path] [-m path]
>>>      [-O option=value] [-S subsection] [-s section] [-T output] [-W level]
>>>      [section] name ...
>>>      ^^^^^^^^^
>>>
>>> But I see no  way of expressing it in the new  man.conf or addressing it
>>> in the  command line.  Here is what  I have added  according to  the new
>>> man.conf(5):
>>>
>>> manpath /usr/local/lib/tcl/tcl8.5/man
>>> manpath /usr/local/lib/tcl/tcl8.6/man

That's not necessarily a good idea; it adds both directories to the
default search path, so you may end up seeing Tcl documentation
when looking for something completely different.  Then again, nothing
wrong with that if you do indeed want to have both Tcl dirs searched
by default...

>>> But I don't see how to use [section] anymore. man(1) does mention using
>>> [-s section] with n as the section, but that only seems to display the
>>> first match of tcl8.5 and does not allow further granularity (as far as
>>> I can tell).
>>>
>>> Have I missed something in the man pages, or what am I doing wrong?

>> i don;t think it's currently possible to do exactly what you propose.
>> i think ingo stripped man.conf pretty bare.

Correct.

In my 2015 BSDCan talk, i offered to implement, in man.conf(5),

  alias aliasname dirname

such that for example

  alias tcl85 /usr/local/lib/tcl/tcl8.5/man

would allow saying

  man -M tcl85 Tcl

But i also said:

  "So far, there is no noticeable demand -> KISS."

That is still true a year later, and personally, i consider
shell aliases a very good solution, not merely a workaround.

All the same, if enough people want the feature, in particular if
somebody can present a compelling argument why shell aliases are
not a good solution, i'm still willing to implement it.

>> the workarounds would be:
>>
>> - have multiple conf files and use man -C to get the one you want
>> - use man -m on the command line (or aliases) to get what you want

That's what i recommend.  For example:

  alias man85="man -M /usr/local/lib/tcl/tcl8.5/man"

That doesn't even require editing /etc/man.conf,
and it can be used like this:

   $ man85 -k search
  Tcl_GetEncodingSearchPath(3) - Tcl_GetEncodingSearchPath
  Tcl_SetEncodingSearchPath(3) - Tcl_SetEncodingSearchPath
  lsearch(n) - lsearch
   $ man85 lsearch
  lsearch(n)              Tcl Built-In Commands             lsearch(n)
  [...]

>> i think man(1) is currently wrong regarding the section values in -s
>> (i'll look into that).

That was just fixed.

> The multiple configuration files is one working approach to multiple
> work directory invocation, and these can coexist.  Then more over so,
> there must be a way to call tcl85 and tcl86 something else than both
> "Tcl" right?  Meaning maybe also seek ways to reconcile these in Tcl
> land & potentially other multiple versions environments.  W/ regards,
> please excuse me, if this is out of line or just plain inappropriate.

I don't think renaming stuff in ports would be wise.  It would cause
a considerable maintenance burden for the port maintainer, and
having stuff renamed to something differing from upstream might
also surprise people who only use one single version.  Having manual
pages of the same name is not a problem as long as they live in
different manpath trees.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to handle different sections with new man.conf?

lists-2
Fri, 1 Jul 2016 22:59:16 +0200 Ingo Schwarze <[hidden email]>

> Hi Andy,
>
> >>> Using OpenBSD 5.8-stable.
> >>>
> >>> I used to have the following in /etc/man.conf:
> >>>
> >>> tcl85           /usr/local/lib/tcl/tcl8.5/man/
> >>> tcl86           /usr/local/lib/tcl/tcl8.6/man/
> >>>
> >>> Which made it easy to view one or the other by using the section
> >>> argument:
> >>>
> >>> man tcl85 Tcl
> >>> man tcl86 Tcl
> >>>
> >>> man(1) still appears to be documented to have this functionality:
> >>>
> >>>  man [-acfhklw] [-C file] [-I os=name] [-K encoding] [-M path] [-m path]
> >>>      [-O option=value] [-S subsection] [-s section] [-T output] [-W level]
> >>>      [section] name ...
> >>>      ^^^^^^^^^
> >>>
> >>> But I see no  way of expressing it in the new  man.conf or addressing it
> >>> in the  command line.  Here is what  I have added  according to  the new
> >>> man.conf(5):
> >>>
> >>> manpath /usr/local/lib/tcl/tcl8.5/man
> >>> manpath /usr/local/lib/tcl/tcl8.6/man  
>
> That's not necessarily a good idea; it adds both directories to the
> default search path, so you may end up seeing Tcl documentation
> when looking for something completely different.  Then again, nothing
> wrong with that if you do indeed want to have both Tcl dirs searched
> by default...
>
> >>> But I don't see how to use [section] anymore. man(1) does mention using
> >>> [-s section] with n as the section, but that only seems to display the
> >>> first match of tcl8.5 and does not allow further granularity (as far as
> >>> I can tell).
> >>>
> >>> Have I missed something in the man pages, or what am I doing wrong?  
>
> >> i don;t think it's currently possible to do exactly what you propose.
> >> i think ingo stripped man.conf pretty bare.  
>
> Correct.
>
> In my 2015 BSDCan talk, i offered to implement, in man.conf(5),
>
>   alias aliasname dirname
>
> such that for example
>
>   alias tcl85 /usr/local/lib/tcl/tcl8.5/man
>
> would allow saying
>
>   man -M tcl85 Tcl
>
> But i also said:
>
>   "So far, there is no noticeable demand -> KISS."
>
> That is still true a year later, and personally, i consider
> shell aliases a very good solution, not merely a workaround.
>
> All the same, if enough people want the feature, in particular if
> somebody can present a compelling argument why shell aliases are
> not a good solution, i'm still willing to implement it.
>
> >> the workarounds would be:
> >>
> >> - have multiple conf files and use man -C to get the one you want
> >> - use man -m on the command line (or aliases) to get what you want  
>
> That's what i recommend.  For example:
>
>   alias man85="man -M /usr/local/lib/tcl/tcl8.5/man"
>
> That doesn't even require editing /etc/man.conf,
> and it can be used like this:
>
>    $ man85 -k search
>   Tcl_GetEncodingSearchPath(3) - Tcl_GetEncodingSearchPath
>   Tcl_SetEncodingSearchPath(3) - Tcl_SetEncodingSearchPath
>   lsearch(n) - lsearch
>    $ man85 lsearch
>   lsearch(n)              Tcl Built-In Commands             lsearch(n)
>   [...]
>
> >> i think man(1) is currently wrong regarding the section values in -s
> >> (i'll look into that).  
>
> That was just fixed.
>
> > The multiple configuration files is one working approach to multiple
> > work directory invocation, and these can coexist.  Then more over so,
> > there must be a way to call tcl85 and tcl86 something else than both
> > "Tcl" right?  Meaning maybe also seek ways to reconcile these in Tcl
> > land & potentially other multiple versions environments.  W/ regards,
> > please excuse me, if this is out of line or just plain inappropriate.  
>
> I don't think renaming stuff in ports would be wise.  It would cause
> a considerable maintenance burden for the port maintainer, and
> having stuff renamed to something differing from upstream might
> also surprise people who only use one single version.

I agree completely, thank you for enumerating these consequences as well.
I presumed it'd be offsetting to add the question of branching & version
numbering of software (programming languages most frequently), ending up
in various cuts (as the "maintained" releases).  Still I wanted to query
your stance on the version names in relation to manual pages, as this is
where it all ends (and just begins depending on view point, introductory
approach, development methods).  Thanks for considering this byway point.

> Having manual pages of the same name is not a problem as long as they
> live in different manpath trees.
>
> Yours,
>   Ingo

Reply | Threaded
Open this post in threaded view
|

Re: How to handle different sections with new man.conf?

Theo de Raadt
> > > there must be a way to call tcl85 and tcl86 something else than both
> > > "Tcl" right?  Meaning maybe also seek ways to reconcile these in Tcl
> > > land & potentially other multiple versions environments.  W/ regards,
> > > please excuse me, if this is out of line or just plain inappropriate.  
> >
> > I don't think renaming stuff in ports would be wise.  It would cause
> > a considerable maintenance burden for the port maintainer, and
> > having stuff renamed to something differing from upstream might
> > also surprise people who only use one single version.
>
> I agree completely, thank you for enumerating these consequences as well.
> I presumed it'd be offsetting to add the question of branching & version
> numbering of software (programming languages most frequently), ending up
> in various cuts (as the "maintained" releases).  Still I wanted to query
> your stance on the version names in relation to manual pages, as this is
> where it all ends (and just begins depending on view point, introductory
> approach, development methods).  Thanks for considering this byway point.

That's a lot of talk for

    "Wow, you are suggesting I should do the work, but I my only
     skill is to post to misc, and wow, that feels too much like
     a call".

End of story.

Please shut up "lists".  Everyone tires of your well articulated
agenda pushes.

Reply | Threaded
Open this post in threaded view
|

Re: How to handle different sections with new man.conf?

Andy Bradford-21
In reply to this post by Ingo Schwarze
Thus said Ingo Schwarze on Fri, 01 Jul 2016 22:59:16 +0200:

> >>> manpath /usr/local/lib/tcl/tcl8.5/man
> >>> manpath /usr/local/lib/tcl/tcl8.6/man
>
> That's not  necessarily a good idea;  it adds both directories  to the
> default search path,  so you may end up seeing  Tcl documentation when
> looking for something completely different.

I see. I was just blindly copying the old directories that I had defined
in man.conf  prior to the  upgrade without realizing that  they wouldn't
have the same effect.

The goal was  to have both sets  of man pages available but  allow me to
choose which version of the man pages to read from.

> Then again, nothing wrong with that if you do indeed want to have both
> Tcl dirs searched by default...

If  I understand  it, however,  I don't  really think  it will  have the
intended  effect, and  while they  would  both be  searched by  default,
matches would  always come from  tcl8.5 and  the only time  tcl8.6 would
match is when there  is a difference that exists in  tcl8.6 only but not
in tcl8.5.

> But i also said:
>
>   "So far, there is no noticeable demand -> KISS."

True enough. My  attempts at retaining prior behavior  are certainly not
``noticeable demand.' :-)

I'll toy around with shell aliases and see where that goes.

Thanks for looking at it.

Andy
--
TAI64 timestamp: 40000000577dd304