# pkg (or pkg_*) syntax woes



## blackhaz (Jan 27, 2015)

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?


----------



## phoenix (Jan 27, 2015)

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.


----------



## blackhaz (Jan 27, 2015)

Wouldn't it be better to have many different pkg-* tools corresponding to their man pages instead of a single giant pkg?


----------



## protocelt (Jan 27, 2015)

blackhaz said:


> Wouldn't it be better to have many different pkg-* tools corresponding to their man pages instead of a single giant pkg?


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)


----------



## protocelt (Jan 28, 2015)

phoenix said:


> It's because man pages can't have spaces in them.


Will this limitation possibly be removed in the future with mandoc() being pulled in?


----------



## blackhaz (Jan 28, 2015)

No, I mean rather than having one giant pkg command, why not have individual pkg-install, pkg-delete, etc commands?


----------



## wblock@ (Jan 28, 2015)

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:

```
alias pkg-install 'pkg install'
alias pkg-delete 'pkg delete'
...
```


----------



## phoenix (Jan 28, 2015)

blackhaz said:


> No, I mean rather than having one giant pkg command, why not have individual pkg-install, pkg-delete, etc commands?



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.


----------



## blackhaz (Jan 29, 2015)

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.


----------



## getopt (Jan 29, 2015)

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)

```
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)
```


----------



## ANOKNUSA (Jan 29, 2015)

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.



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.


----------



## blackhaz (Jan 29, 2015)

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?


----------



## ANOKNUSA (Jan 30, 2015)

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?



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.


----------



## SirDice (Jan 30, 2015)

blackhaz said:


> My thinking was that a man page name should correspond to something tangible - a command or a function.


I can name a few that aren't tangible, hier(7), ports(7), release(7), build(7), intro(1), security(7). And those are only the ones I know from the top of my head. I'm sure there are a few more.


----------

