pkg (or pkg_*) syntax woes

blackhaz

blackhaz

Dear FreeBSD users,

I apologize if this has been raised before. Could somebody tell me why pkg has this funny syntax with space? To me, all it does is breaks logic. I understand this is a complex tool, however there should be a better way to work with syntax. There are pkg commands, such as install, info, delete, etc. Then, there are pkg-install, pkg-info, pkg-delete, etc - which are not even binaries or scripts, yet man pages link to them as they are. If I want to install something, I do:

pkg install ...

With a space. However, if I want a man page on this particular function of pkg then I have to do:

man pkg-install

With a dash. But when I try pkg-install command, it is, of course, not found. Or even worse, as far as I am concerned:

pkg install help

Which is a rather non-standard way to obtain documentation and a system of its own. (We don't do ls help, for example.) Why do we have spaces in the syntax at all? Why not use dash everywhere and, thus, bring the pkg syntax and man usage into the same style?
 
It's because man pages can't have spaces in them. The following command fails:
$ man pkg install

They could have created a single, giant, enormous, 70+ screen man page for pkg(8). Or, they could split it into separate man pages according to the sub-command, which they did: pkg-install(8)

There's precedent for this. Have a look at the zsh(1) man page and compare it to the output of (on a system with shells/zsh installed):
$ man -k zsh

It's the same thing there: a small page that describes the other pages, and separate zsh-<sub-sections> man pages.
 
Wouldn't it be better to have many different pkg-* tools corresponding to their man pages instead of a single giant pkg?
 
blackhaz said:
Wouldn't it be better to have many different pkg-* tools corresponding to their man pages instead of a single giant pkg?
Click to expand...
I don't know if you meant to say something different, but that is exactly what phoenix said they did in the post above.
phoenix said:
They could have created a single, giant, enormous, 70+ screen man page for pkg(8). Or, they could split it into separate man pages according to the sub-command, which they did: pkg-install(8)
Click to expand...
 
No, I mean rather than having one giant pkg command, why not have individual pkg-install, pkg-delete, etc commands?
 
Other than typing a dash or a space, how would that improve things? If the dash in the man page name is such a problem, why not just:
Code: 
alias pkg-install 'pkg install'
alias pkg-delete 'pkg delete'
...
 
blackhaz said:
No, I mean rather than having one giant pkg command, why not have individual pkg-install, pkg-delete, etc commands?
Click to expand...

Which is easier to remember? A single pkg command that has great built-in help and a single man page that directs you to where you need to be (see the SEE ALSO section of pkg(8))? Or a slew of pkg-stuff commands?

For those more familiar with Linux, which is easier to remember: aptitude, or the 15-odd different apt-* commands?

pkg(8) works no differently than the zpool(1) and zfs(1) commands (and those were part of FreeBSD first). I can even see a day when the man pages for those are split into separate zpool-command and zfs-command man pages if anymore sub-commands are added to them. They're already getting to be cumbersome.
 
In order to assess the consequence of what is easier to remember, let us become a little Kantian here with the said built-in help. I am not a UNIX expert but this looks rather unconventional to get a man page, isn't it? What if other utilities would start doing the same? Would this be something appreciated in the BSD world? What if more system utilities will start implementing their own weird syntax for getting man pages? From this standpoint, I appreciate man [I]something[/I] more than [I]something[/I] help. Since zpool(8) and zsh(1) are already doing this I guess everybody are OK with manual sections names not corresponding to the actual command syntax. A number of different pkg_* commands would have been dearer to me from conventional standpoint.
 
blackhaz

You titled your post "pkg (or pkg_*) syntax woes".
If you just could memorize to use man pkg-* your woes would go away.

See pkg(8)
Code: 
SEE ALSO
     SBUF(9), elf(3), fetch(3), libarchive(3), pkg_printf(3), pkg_repos(3), pkg-repository(5), pkg.conf(5), pkg-add(8),
     pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-backup(8), pkg-check(8), pkg-clean(8), pkg-config(8), pkg-convert(8),
     pkg-create(8), pkg-delete(8), pkg-fetch(8), pkg-info(8), pkg-install(8), pkg-lock(8), pkg-query(8), pkg-register(8),
     pkg-repo(8), pkg-rquery(8), pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8), pkg-stats(8), pkg-update(8),
     pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8)
 
blackhaz said:
In order to assess the consequence of what is easier to remember, let us become a little Kantian here with the said built-in help. I am not a UNIX expert but this looks rather unconventional to get a man page, isn't it? What if other utilities would start doing the same? Would this be something appreciated in the BSD world? What if more system utilities will start implementing their own weird syntax for getting man pages? From this standpoint, I appreciate man [I]something[/I] more than [I]something[/I] help. Since zpool(8) and zsh(1) are already doing this I guess everybody are OK with manual sections names not corresponding to the actual command syntax. A number of different pkg_* commands would have been dearer to me from conventional standpoint.
Click to expand...

I can't fathom why you think completely rewriting the package management scheme takes less effort than remembering a hyphen. Besides, pkg isn't unique in this---git(1) does the same thing, and the man pages for zsh(1) are split into a bunch of categories that don't pertain to any commands at all. There's nothing "weird" about the pkg man pages---they're organized for clarity and simplicity, and named so as to work around a limitation of a decades-old program.
 
I didn't say it takes less effort. But we could get away without having to remember that hyphen. My thinking was that a man page name should correspond to something tangible - a command or a function. Is the global consensus that it shouldn't? Majority of man pages names follow that logic then why should we break it? I would rather follow the logic of traditional UNIX commands rather than git(1). I understand it is a work around. But is it the right way to do this?
 
blackhaz said:
I didn't say it takes less effort. But we could get away without having to remember that hyphen. My thinking was that a man page name should correspond to something tangible - a command or a function. Is the global consensus that it shouldn't? Majority of man pages names follow that logic then why should we break it? I would rather follow the logic of traditional UNIX commands rather than git(1). I understand it is a work around. But is it the right way to do this?
Click to expand...

You're familiar with the adage about making mountains out of molehills, right? This is incredibly inane. Read through all the pkg(8) documentation. By the time you're done, a) you'll understand the package manager better than many of us, and b) the hyphen won't bother you anymore.
 
You must log in or register to reply here.
Back
Top