[pacman-dev] Obscurity in pacman.conf.5 man page

[Eli Schwartz]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 1601 bytes
Desc: OpenPGP digital signature
URL: <https://lists.archlinux.org/pipermail/pacman-dev/attachments/20190705/2c1f97ba/attachment.sig>