[pacman-dev] Obscurity in pacman.conf.5 man page
Hello, I stumbled upon the following sentence in pacman.conf.5: repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz The above command will generate a compressed database named /home/pkgs/custom.db.tar.gz. Note that the database must be of the form defined in the configuration file and {ext} is a valid compression type as documented in repo-add(8). Although the example database name has the static extension ».gz« (which is currently used in Archlinux' Pacman), the following explanation mentions {ext} as a variable for the file extension. If this targets to use cases of Pacman in other distributions which possibly use a different extension, then the man page should explain this more detailed. Best Regards, Mario
On 7/5/19 4:44 PM, Mario Blättermann wrote:
Hello,
I stumbled upon the following sentence in pacman.conf.5:
repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz
The above command will generate a compressed database named /home/pkgs/custom.db.tar.gz. Note that the database must be of the form defined in the configuration file and {ext} is a valid compression type as documented in repo-add(8).
Although the example database name has the static extension ».gz« (which is currently used in Archlinux' Pacman), the following explanation mentions {ext} as a variable for the file extension. If this targets to use cases of Pacman in other distributions which possibly use a different extension, then the man page should explain this more detailed.
It has nothing to do with other distributions. You can create a custom repository for personal use using whichever extension you like, too. If you truly wish to know how repo-add works, though, you should be reading the repo-add.8 man page. pacman.conf.5 merely mentions one example use and explicitly tells you which other man page you need to read. -- Eli Schwartz Bug Wrangler and Trusted User
Hello Eli, Am Fr., 5. Juli 2019 um 22:59 Uhr schrieb Eli Schwartz <eschwartz@archlinux.org>:
On 7/5/19 4:44 PM, Mario Blättermann wrote:
Hello,
I stumbled upon the following sentence in pacman.conf.5:
repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz
The above command will generate a compressed database named /home/pkgs/custom.db.tar.gz. Note that the database must be of the form defined in the configuration file and {ext} is a valid compression type as documented in repo-add(8).
Although the example database name has the static extension ».gz« (which is currently used in Archlinux' Pacman), the following explanation mentions {ext} as a variable for the file extension. If this targets to use cases of Pacman in other distributions which possibly use a different extension, then the man page should explain this more detailed.
It has nothing to do with other distributions. You can create a custom repository for personal use using whichever extension you like, too. If you truly wish to know how repo-add works, though, you should be reading the repo-add.8 man page.
pacman.conf.5 merely mentions one example use and explicitly tells you which other man page you need to read.
But the file name /home/pkgs/custom.db.tar.gz is confusing. Should be rather /home/pkgs/custom.db.tar.{ext}. With the current file name, readers think that the extension is hard coded to »gz«, and the following explanation speaks about »ext« which is nowhere to see in the file name. Best Regards, Mario
On Fri, Jul 05, 2019 at 11:09:09PM +0200, Mario Blättermann wrote:
readers think that the extension is hard coded to »gz«, and the following explanation speaks about > »ext« which is nowhere to see in the file name.
I didn't think it was hard coded. Give us some credit, we're not all idiots.
Am Fr., 5. Juli 2019 um 23:29 Uhr schrieb Earnestly via pacman-dev <pacman-dev@archlinux.org>:
On Fri, Jul 05, 2019 at 11:09:09PM +0200, Mario Blättermann wrote:
readers think that the extension is hard coded to »gz«, and the following explanation speaks about > »ext« which is nowhere to see in the file name.
I didn't think it was hard coded. Give us some credit, we're not all idiots.
But for the idiots among the readers, it could be helpful to see the connection between the file name and the later mentioned variable {ext}. Cheers, Mario
Am Fr., 5. Juli 2019 um 22:59 Uhr schrieb Eli Schwartz <eschwartz@archlinux.org>:
On 7/5/19 4:44 PM, Mario Blättermann wrote:
Hello,
I stumbled upon the following sentence in pacman.conf.5:
repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz
The above command will generate a compressed database named /home/pkgs/custom.db.tar.gz. Note that the database must be of the form defined in the configuration file and {ext} is a valid compression type as documented in repo-add(8).
Although the example database name has the static extension ».gz« (which is currently used in Archlinux' Pacman), the following explanation mentions {ext} as a variable for the file extension. If this targets to use cases of Pacman in other distributions which possibly use a different extension, then the man page should explain this more detailed.
It has nothing to do with other distributions. You can create a custom repository for personal use using whichever extension you like, too. If you truly wish to know how repo-add works, though, you should be reading the repo-add.8 man page.
pacman.conf.5 merely mentions one example use and explicitly tells you which other man page you need to read.
To mention, I've translated repo-add.8 into German some months ago (for the manpages-de project), so you may assume that I've read the man page carefully. I don't see this ambiguous {ext} there, so why not simply write »extension« instead, to make it clearer and don't let readers search for a variable of this name anywhere…? Cheers, Mario
On 7/5/19 5:49 PM, Mario Blättermann wrote:
To mention, I've translated repo-add.8 into German some months ago (for the manpages-de project), so you may assume that I've read the man page carefully.
When I say "you need to read" it is the rhetorical "you", which means that I am not speaking to Mario Blättermann -- I am speaking to any prospective reader of the pacman.conf man page. Whether you've translated it to German or not isn't relevant in that context. Actually I hope every repo-add user reads the repo-add man page carefully.
I don't see this ambiguous {ext} there, so why not simply write »extension« instead, to make it clearer and don't let readers search for a variable of this name anywhere…?
Because "ext" is a common abbreviation of "extension", it does not have the variable reference notation "$" preceding it, and because if anyone really thought it was not clear, they would read the repo-add man page. Now, since both of the people who responded to you so far thought this was intuitive, it would seem that at least some readers don't need to do any sort of search. Personally, since *I* feel this is intuitive, I shall not try to revise the man page -- it is not worth my time. You are more than welcome, however, to submit patches to make the man page clearer in whatever manner you wish -- I'm unlikely to object to anything that adds more documentation, and if even one user thinks that it's easier to understand that way, then my gut reaction will be "okay I guess, it doesn't seem to hurt -- thanks for the contribution". -- Eli Schwartz Bug Wrangler and Trusted User
participants (3)
-
Earnestly
-
Eli Schwartz
-
Mario Blättermann