Date: Wed, 1 Jul 2026 15:15:36 -0700 From: Mark Millard <marklmi@yahoo.com> To: Alexander Ziaee <ziaee@FreeBSD.org>, Larry Fahnoe <fahnoe@fahnoetech.com> Cc: Roger Marquis <marquis@roble.com>, freebsd-pkgbase <freebsd-pkgbase@freebsd.org> Subject: Re: None of "man freebsd-base" (or "man pkgbase"), "man pkg-upgrade", or "man pkg-install" deal with documenting .pkgsave and/or .pkgnew behavior or how to handle such Message-ID: <c369de0c-12c7-41b8-afe7-6613c9678260@yahoo.com> In-Reply-To: <E1wexd8-00058p-NX@rmmprod06.runbox> References: <Totf3jwo9_2gIEq6WRkiZel_OK54y4TY_DxkOW5CePGlkSthO3S_0cUuTCNeEaW673tTQDvBAzgpbc8o0Uu49mb3A-nc0GMT-Juf4MN4amE=@fahnoetech.com> <E1wexd8-00058p-NX@rmmprod06.runbox>
index | next in thread | previous in thread | raw e-mail
On 7/1/26 09:17, Alexander Ziaee wrote: > On 2026-07-01 08:57 -04:00 EDT, "Larry Fahnoe" <fahnoe@fahnoetech.com> wrote: >> My bringing up my own sysadmin experience on other operating systems did not add meaningfully to the conversation and has needlessly stirred the pot. > > I think your words really added meaningfully to the conversation, it brought 3 important ideas to light. From my end as a writer I learned that people are interpreting the information landscape to mean that FreeBSD has a unique issue, when actually VMS and Linux operate the exact same way. Long ago I used VAX/VMS and so was familiar with the likes of ;2 file name suffixes in that context. I never thought that the general type of issue is unique to FreeBSD or to pkg . > So I have a lot more context to reflect on needed improvements to our information landscape. Second, it shows that actually we have the opportunity to solve an unsolved problem in operating systems right now. That is particularly exciting to me because I really love it when we have one of the oldest continuously maintained codebases in the world and are still in places on the bleeding edge working on unsolved problems. Third, I think this was informative for many of our readers who administer mixed environments (which is probably most of us, including me) who may now know that they have and should seek to resolve failed configuration merges in their other environments. > > Plus, the thread didn't catch fire, so w/rt stirring the pot, its all good. > >> I believe this to be a pkg issue, and downstream of that a documentation issue. > > I shared the concerns I'm trying to balance, do you have any ideas how we can make the docs better? > Currently, I've documented these in the 15.1 upgrading guide, and the pkg(8) manual. I do not automatically (re)read the pkg(8) manual to learn about or remind myself of the specifics of what pkg install and pkg upgrade do or requires-of-me for aspects that the command output is silent about. So far as I know, no other pkg commands generate such files. In my view each of those 2 man pages for should at least explicitly indicate to where to look up information about the 3 types of files at issue, including use of notation that allows one to be able to identify the naming conventions involved. But I also think that the command output should explicitly indicate if the results happen to have generated files to go looking for. That allows knowing one can avoid looking when no such file was actually generated --and when one needs to consider looking otherwise (for each type with a positive count). The man pages can not cover such command instance information that guides later actions. >I don't want to duplicate information because it makes an unsustainable maintenance burden, but we can link to these, or if it makes more sense we can move them, and we can also link to them. Further, the descriptions themselves can always be improved. > > Best, > Alex > -- === Mark Millard marklmi at yahoo.comhome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?c369de0c-12c7-41b8-afe7-6613c9678260>