Re: A request to segregate man pages for shell built-ins

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

Re: A request to segregate man pages for shell built-ins

Matthew Seaman-2
On 25/10/2017 03:23, Manish Jain wrote:
> (Note : some built-ins (e.g. 'test') do have their own man pages)

That's because there's a stand-alone test(1) as well as a shell built-in.

> Is it not possible to create separate man pages for the shell built-ins
> too ? Or at least ensure that invoking the built-in with --help gets the
> necessary information ?

I'm sure creating separate man pages is possible: it's just a question
of someone stepping up and doing the work.

        Cheers,

        Matthew


signature.asc (949 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Erwan David
Le 25 octobre 2017 08:14:47 Matthew Seaman <[hidden email]> a écrit :

> On 25/10/2017 03:23, Manish Jain wrote:
>> (Note : some built-ins (e.g. 'test') do have their own man pages)
>
> That's because there's a stand-alone test(1) as well as a shell built-in.
>
>> Is it not possible to create separate man pages for the shell built-ins
>> too ? Or at least ensure that invoking the built-in with --help gets the
>> necessary information ?
>
> I'm sure creating separate man pages is possible: it's just a question
> of someone stepping up and doing the work.
>
> Cheers,
>
> Matthew
>

That would mean doing a new section per shell eg (1bash) (1csh) (1zsh) each
shell has its own builtins, Hicham can differ (compare set in bash and csh )

--
Erwan David


_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Manish Jain-2


On 10/25/17 13:23, Erwan DAVID wrote:
> That would mean doing a new section per shell eg (1bash) (1csh) (1zsh)
> each shell has its own builtins, Hicham can differ (compare set in bash
> and csh )

Perhaps a new, unique section of man pages (something like section 99)
implemented for sh only and which can be called by any shell with the
same syntax : 'man 99 set'

Tx
Manish Jain
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Thomas Mueller-6
In reply to this post by Matthew Seaman-2

from Manish Jain:

> Despite all the respect I have for the genius of Richard Stallman, I
> could never understand what use was his idea of info - man pages are
> what everyone needs, and nothing else.

> But I run into roughly the same weather with shell built-ins, most of
> which do not have their own man page. 'man set' rather blandly throws up
> the man page for the shell, and it takes an immense effort to glean the
> relevant information.
       
> Is it not possible to create separate man pages for the shell built-ins
> too ? Or at least ensure that invoking the built-in with --help gets the
> necessary information ?

> (Note : some built-ins (e.g. 'test') do have their own man pages)

I agree, info is a bummer, html would be better, but man works on the base system with no web browser, you don't even need lynx or elinks.

There is a pinfo port.  Konqueror in KDE had a good info viewer.  But still, sticking with man makes more sense.

If you run man on a shell builtin and get the man page for the shell, you can search through the man page on the desired command.

Tom

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Matthew Seaman-2
In reply to this post by Matthew Seaman-2
On 25/10/2017 09:56, Sijmen J. Mulder wrote:

> Whilst I do appreciate builtin(1)'s comprehensiveness I too find it hard
> to nagivate.
>
> Op 25-10-2017 om 10:10 schreef Matthew Seaman:
>> In the case of eg. echo(1), I'd be happy to see the existing page for
>> the stand-alone echo refactored to cover all of the different flavours
>> of echo -- the behaviour is much the same in most use cases -- plus some
>> discussion on how the variants differ.
>
> This seems like a good solution. But, how would shells in ports deal
> with this? A builtin(1)-like foosh(1), or foosh_echo(1), foosh_case(1),
> etc?

Outside projects will do their own thing.  We can (as the FreeBSD
project) provide our own man pages for a FreeBSD port where we think
that what upstream provides is deficient, and we can submit those pages
upstream as good citizens are supposed to, but again, this relies
entirely on someone volunteering to step up and do the work.  However,
it's unlikely that we'd want to try and integrate or combine man pages
from external projects with base system manpages in any significant way.
 That's far too complex and fragile to be worth the effort.
/usr/share/man and /usr/local/man are different worlds.

        Cheers,

        Matthew
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Dave-8
In reply to this post by Manish Jain-2
On Wednesday 25 October 2017 08:03:03 Manish Jain wrote:
>
> On 10/25/17 13:23, Erwan DAVID wrote:
> > That would mean doing a new section per shell eg (1bash) (1csh) (1zsh)
> > each shell has its own builtins, Hicham can differ (compare set in bash
> > and csh )
>
> Perhaps a new, unique section of man pages (something like section 99)
> implemented for sh only and which can be called by any shell with the
> same syntax : 'man 99 set'

Does man allow for multiple arguments and does the man page structure allow
for book marks?  eg man bash echo could display the bash man page at the echo
command.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Manish Jain-2
>
> Does man allow for multiple arguments and does the man page structure allow
> for book marks?  eg man bash echo could display the bash man page at the echo
> command.

Well, I am talking about a section which is simply unique in its section
number, where the sh implementation would have to have to be understood
by any invoking application (shells included) - because it is the
section reserved for sh built-ins.

If the current man implementation's architectural overhaul can lead to a
major benefit for every Unix user, why not?

FreeBSD has always been the pioneer. This change allows huge ease when
referring to much-needed information quickly enough.

Tx
Manish Jain
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Polytropon
In reply to this post by Matthew Seaman-2
On Wed, 25 Oct 2017 02:23:23 +0000, Manish Jain wrote:
> But I run into roughly the same weather with shell built-ins, most of
> which do not have their own man page. 'man set' rather blandly throws up
> the man page for the shell, and it takes an immense effort to glean the
> relevant information.
>
> Is it not possible to create separate man pages for the shell built-ins
> too ? Or at least ensure that invoking the built-in with --help gets the
> necessary information ?

The key problem is that different shells might have a builtin
with the same name, but different syntax or behaviour. That's
why you typically use "man sh" or "man csh" and then search
for the builtin within that man page.



> (Note : some built-ins (e.g. 'test') do have their own man pages)

Well, test is a binary, a separate program, not a builtin. ;-)

        % which test
        /bin/test

        % which [
        /bin/[

Of course, [ and test are actually one and the same binary.

Keep in mind some shells also offer a builtin replacement for
an existing binary. A good example is echo where a binary exists,
but the C Shell has its own internal echo, while BASH uses the
binary one:

        % which echo
        echo: shell built-in command.

        $ which echo
        /bin/echo

In such a case, what should "man echo" show?


--
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Polytropon
In reply to this post by Manish Jain-2
On Wed, 25 Oct 2017 08:03:03 +0000, Manish Jain wrote:

>
>
> On 10/25/17 13:23, Erwan DAVID wrote:
> > That would mean doing a new section per shell eg (1bash) (1csh) (1zsh)
> > each shell has its own builtins, Hicham can differ (compare set in bash
> > and csh )
>
> Perhaps a new, unique section of man pages (something like section 99)
> implemented for sh only and which can be called by any shell with the
> same syntax : 'man 99 set'

Or like pkg's "sub-manpages", with a hyphen:

        % man echo-csh

compared to

        % man test-bash

And for "identical implementations", compound manuals just as if
you'd use "man 3 malloc" or "man 3 calloc" to take you to the same
manual page.


--
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Rafal Lukawiecki
In reply to this post by Matthew Seaman-2
For what it is worth, I would have found this segregated access to man for shell built-ins very useful in the last two months, as I have been rapidly re-skilling from bash/Linux to sh/FreeBSD. I spent too much time browsing the net while, ideally, most of it could have come from man.

Anything that makes it easier to get up to speed with sh is going to make FreeBSD more accessible, especially to those coming from bash, in my opinion.

However, it is also quite useful to have a single, long document on sh, which is capable of covering the more general issues such as variable scope and flow control. I wonder if there is a risk that a segregated approach could remove that important benefit.
--
Rafal Lukawiecki
Data Scientist
Project Botticelli Ltd

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Polytropon
On Wed, 25 Oct 2017 14:49:26 +0100, Rafal Lukawiecki wrote:

> For what it is worth, I would have found this segregated access to man for shell built-ins very useful in the last two months, as I have been rapidly re-skilling from bash/Linux to sh/FreeBSD. I spent too much time browsing the net while, ideally, most of it could have come from man.
>
> Anything that makes it easier to get up to speed with sh is going
> to make FreeBSD more accessible, especially to those coming from
> bash, in my opinion.
>
> However, it is also quite useful to have a single, long document
> on sh, which is capable of covering the more general issues such
> as variable scope and flow control. I wonder if there is a risk
> that a segregated approach could remove that important benefit.

This probably could be solved by incorporating shell-specific
sections and "SEE ALSO" into the manpages which already exist
for external commands (e. g., "man test"), and adding new pages
for builtins (one could be "man for" or "man while" where there
is a difference in sh/bash and csh syntax and usage). The general
coverage provided by "man sh", "man csh" or "man bash" should not
be distributed among "little man pages", as this also makes searching
for context problematic (simply because what you're searching for
is in another manpage, not in the one you validly used as an entry
point).



--
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
zep
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

zep
In reply to this post by Polytropon
On 10/25/2017 09:22 AM, Polytropon wrote:

> On Wed, 25 Oct 2017 08:03:03 +0000, Manish Jain wrote:
>>
>> On 10/25/17 13:23, Erwan DAVID wrote:
>>> That would mean doing a new section per shell eg (1bash) (1csh) (1zsh)
>>> each shell has its own builtins, Hicham can differ (compare set in bash
>>> and csh )
>> Perhaps a new, unique section of man pages (something like section 99)
>> implemented for sh only and which can be called by any shell with the
>> same syntax : 'man 99 set'
> Or like pkg's "sub-manpages", with a hyphen:
>
> % man echo-csh
>
> compared to
>
> % man test-bash
>
> And for "identical implementations", compound manuals just as if
> you'd use "man 3 malloc" or "man 3 calloc" to take you to the same
> manual page.
>

you could also build a 'smarter' man in such a case - e.g. as a shell
script wrapper kinda thing, it could do a which first, find out if the
shell you're currently running it from has a builtin, if there's a
binary, then chose the right one for how it's called and possibly
include a caveat about other versions.

not that I'm saying I'm ready to take on such a task, just offering some
suggestions.

--

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Polytropon
On Wed, 25 Oct 2017 10:10:05 -0400, zep wrote:

> On 10/25/2017 09:22 AM, Polytropon wrote:
> > On Wed, 25 Oct 2017 08:03:03 +0000, Manish Jain wrote:
> >>
> >> On 10/25/17 13:23, Erwan DAVID wrote:
> >>> That would mean doing a new section per shell eg (1bash) (1csh) (1zsh)
> >>> each shell has its own builtins, Hicham can differ (compare set in bash
> >>> and csh )
> >> Perhaps a new, unique section of man pages (something like section 99)
> >> implemented for sh only and which can be called by any shell with the
> >> same syntax : 'man 99 set'
> > Or like pkg's "sub-manpages", with a hyphen:
> >
> > % man echo-csh
> >
> > compared to
> >
> > % man test-bash
> >
> > And for "identical implementations", compound manuals just as if
> > you'd use "man 3 malloc" or "man 3 calloc" to take you to the same
> > manual page.
> >
>
> you could also build a 'smarter' man in such a case - e.g. as a shell
> script wrapper kinda thing, it could do a which first, find out if the
> shell you're currently running it from has a builtin, if there's a
> binary, then chose the right one for how it's called and possibly
> include a caveat about other versions.

This is possible, but there is the following obstacle:

A shell can invoke an external command or a builtin depending
on execution context, i. e., if the shell is currently processing
a shell script, the builtin will be used, but if it runs an
interactive session, the external command will be called.

I cannot remember what shell it was, but I encountered this
strange behaviour once, many years ago: Something that worked
at the command line didn't work the same way when used inside
a shell script, even though the text was used 1:1. It was on
some expensive UNIX nobody remembers anymore... ;-)





--
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Daniel Feenberg
In reply to this post by Polytropon


On Wed, 25 Oct 2017, Polytropon wrote:

>
> % which echo
> echo: shell built-in command.
>
> $ which echo
> /bin/echo
>
> In such a case, what should "man echo" show?
>

A person of good will authoring the documentation would describe the
difference.

The problem with putting all the documentation for several score of shell
commands in a single page is not for commands such as "echo" which are
easy to search for on the builtins man page, but commands such as "if"
which are quite a chore to search for. I don't advocate a change in
policy, but I wouldn't ridicule proponents in favor of a change.

In any case, it is disengenuous to suggest to someone that they write the
pages, given that there is no chance that such pages would be included in
the distribution.

daniel feenberg
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Karl Vogel-4
In reply to this post by Matthew Seaman-2
On Wed, Oct 25, 2017 at 07:14:28AM +0100, Matthew Seaman wrote:

> I'm sure creating separate man pages is possible: it's just a question
> of someone stepping up and doing the work.

  Here's a "solution" from the baling-twine-and-ductape school of coding.
  I ran "compgen -b" under bash and got a list of builtins:

    .
    :
    [
    alias
    [...]
    unalias
    unset
    wait

  A little vi:

    help . >  dot.1
    help : > :.1
    help [ > [.1
    help alias > alias.1
    help unalias > unalias.1
    help unset > unset.1
    help wait > wait.1

  Run "strings" on /path/to/man and find the default MANSECT.  Stick all
  these files under /usr/local/man/cat1b and give it a test-drive:

    #!/bin/ksh
    #<myman: quick manpage test
    export PATH=/usr/local/bin:/bin:/usr/bin
    export MANSECT=1b:1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o

    case "$1" in
        .) page=dot ;;
        *) page=$1 ;;
    esac

    man $page
    exit 0

  You could do something just as hideous for ksh/tcsh/whatever and put
  the results under separate sections.  In one of your login dotfiles:

    export MANSECT=1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o

    case "$SHELL" in
        *bash)  add="1b" ;;
        *csh)   add="1c" ;;
        *zsh)   add="1z" ;;
    esac

    MANSECT="${add}:$MANSECT"

... I'll show myself out.

--
Karl Vogel                      I don't speak for the USAF or my company

You're the type of guy who'd give a Rubik's Cube to Forrest Gump.
                                                     --Local DJ, station Z93

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Ian Smith
In reply to this post by Matthew Seaman-2
In freebsd-questions Digest, Vol 699, Issue 4, Message: 3
On Wed, 25 Oct 2017 15:16:47 +0200 Polytropon <[hidden email]> wrote:

 > On Wed, 25 Oct 2017 02:23:23 +0000, Manish Jain wrote:
 > > But I run into roughly the same weather with shell built-ins, most of
 > > which do not have their own man page. 'man set' rather blandly throws up
 > > the man page for the shell, and it takes an immense effort to glean the
 > > relevant information.

Trouble is, it all depends on what shell you're using - at a given time.

 > > Is it not possible to create separate man pages for the shell built-ins
 > > too ? Or at least ensure that invoking the built-in with --help gets the
 > > necessary information ?

builtin(1) has always worked for me.  But then, I only use sh(1) for
scripting and csh(1) interactively, and they're the only two it covers.

 > The key problem is that different shells might have a builtin
 > with the same name, but different syntax or behaviour. That's
 > why you typically use "man sh" or "man csh" and then search
 > for the builtin within that man page.

Yes, after consulting builtin(1) perhaps ..

 > > (Note : some built-ins (e.g. 'test') do have their own man pages)
 >
 > Well, test is a binary, a separate program, not a builtin. ;-)
 >
 > % which test
 > /bin/test
 >
 > % which [
 > /bin/[

% which test
/bin/test
% sh
$ which test
/bin/test

These results are correct for test, but it _is_ builtin to sh(1):

     [       A built-in equivalent of test(1).
     test    A built-in equivalent of test(1).

Fortunately - or it'd be much slower with, um, testing.  So which isn't
aware of the sh(1) builtin (since sh(1) has no 'which' builtin, so uses
which(1)) .. whereas csh(1) has builtin which but no 'test' (as such,
though all test's, um, tests can be done in csh).  Easily confusing, eh?

           Command       External    csh(1)    sh(1)
           echo          Yes         Yes       Yes
           test          Yes         No        Yes

 > Of course, [ and test are actually one and the same binary.

And the builtin test in sh(1) is correctly covered by test(1).

 > Keep in mind some shells also offer a builtin replacement for
 > an existing binary. A good example is echo where a binary exists,
 > but the C Shell has its own internal echo, while BASH uses the
 > binary one:
 >
 > % which echo
 > echo: shell built-in command.
 >
 > $ which echo
 > /bin/echo

Again, despite that, echo _is_ builtin to sh(1) - and has more options.

 > In such a case, what should "man echo" show?

Among other things, see builtin(1)" .. oh, it already does.

Perhaps sh(1) could use a smarter 'which' that exposes its own builtins
such as these two more readily - but who dares mess with sh(1) ? :)

cheers, Ian
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: A request to segregate man pages for shell built-ins

Polytropon
On Fri, 27 Oct 2017 03:02:17 +1100 (EST), Ian Smith wrote:

> In freebsd-questions Digest, Vol 699, Issue 4, Message: 3
> On Wed, 25 Oct 2017 15:16:47 +0200 Polytropon <[hidden email]> wrote:
>
>  > On Wed, 25 Oct 2017 02:23:23 +0000, Manish Jain wrote:
>  > > [...]
>  > > (Note : some built-ins (e.g. 'test') do have their own man pages)
>  >
>  > Well, test is a binary, a separate program, not a builtin. ;-)
>  >
>  > % which test
>  > /bin/test
>  >
>  > % which [
>  > /bin/[
>
> % which test
> /bin/test
> % sh
> $ which test
> /bin/test
>
> These results are correct for test, but it _is_ builtin to sh(1):
>
>      [       A built-in equivalent of test(1).
>      test    A built-in equivalent of test(1).

Yes, this is true as long as the script uses [ or test. Some do
explicitely call /bin/test. I'm almost sure this isn't true anymore
on today's modern FreeBSD, but older UNIX scripts occassionally
were constructed in such a way that they called the binaries
explicitely with the full path. Maybe this has been some portability
issue.



> Fortunately - or it'd be much slower with, um, testing.  So which isn't
> aware of the sh(1) builtin (since sh(1) has no 'which' builtin, so uses
> which(1)) .. whereas csh(1) has builtin which but no 'test' (as such,
> though all test's, um, tests can be done in csh).  Easily confusing, eh?
>
>            Command       External    csh(1)    sh(1)
>            echo          Yes         Yes       Yes
>            test          Yes         No        Yes

To complete that table:

           Command       External    csh(1)    sh(1)
           which         Yes         Yes       No

So the result of the command is a bit confusing as "which", no
matter if being internal or external, is showing the binary as
a result whereas it should show builtin. Maybe this is another
"fight" between external and builtin?

Oh, and nobody with a sane mind writes shell scripts in C Shell.
Of course I've done it. ;-)



>  > Of course, [ and test are actually one and the same binary.
>
> And the builtin test in sh(1) is correctly covered by test(1).

Yes, sh implements it as per the manpage.



>  > Keep in mind some shells also offer a builtin replacement for
>  > an existing binary. A good example is echo where a binary exists,
>  > but the C Shell has its own internal echo, while BASH uses the
>  > binary one:
>  >
>  > % which echo
>  > echo: shell built-in command.
>  >
>  > $ which echo
>  > /bin/echo
>
> Again, despite that, echo _is_ builtin to sh(1) - and has more options.

That is correct (even though sh's "which echo" reports the binary);
sh's echo supports escape sequences using the -e option, while the
binary doesn't.



>  > In such a case, what should "man echo" show?
>
> Among other things, see builtin(1)" .. oh, it already does.
>
> Perhaps sh(1) could use a smarter 'which' that exposes its own builtins
> such as these two more readily - but who dares mess with sh(1) ? :)

Interactively? Probably only the poor souls dropped into
maintenance mode (single user mode) without the ability to
start a more comfortable interactive shell... ;-)



--
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-questions
To unsubscribe, send any mail to "[hidden email]"