Introduction to File Formats - 21st Century BSD #1534
Conversation
New users are sometimes confused about the difference between /etc/ and /usr/local/etc. Explain this in the manual as we did in intro(1). MFC after: 3 days
Looking around at how everyone else is doing it, This list seems nearly perfect to me and we should just import it from them. I have added "and streams" because we have some explanations of those in here too. MFC after: 3 days Obtained from: OpenBSD
Explain a little about everything is a file, matching the style of earlier intro pages. MFC after: 3 days
There was a problem hiding this comment.
A nice improvement!
I consider these intro pages to be a "landing page" for a particular section, and should provide a new reader with some "further reading". It would be useful to have a list of links to popular/useful pages within section 5, sort of like intro(7) or intro(9). Perhaps done as several sub-lists of the items you have added already.
This is not a requirement for this PR, just my suggestion on how it can be improved further.
Co-authored-by: Mitchell Horne <[email protected]>
| .It Pa /etc/ | ||
| location of most base system configuration files | ||
| .It Pa /usr/local/etc/ | ||
| location of installed component configuration files |
There was a problem hiding this comment.
i appreciate there's a desire to be terse here, but this wording seems a bit odd to me.
for unfortunate historical reasons, /usr/local/etc contains two separate, unrelated types of file:
- user-created configuration files for locally-installed software
- configuration files for software installed from FreeBSD ports/packages
however:
- not every 'installed component' is guaranteed to go to
/usr/local/etc(e.g. pkgsrc, OpenPKG) - the installation prefix of ports (
LOCALBASE) can be changed when building them
perhaps this could be written as something like:
typical location of configuration files for locally-installed software, and default location of configuration files for software installed from FreeBSD ports
(or, you know, something less awkward -- there's a reason i'm not a doc author.)
and an Xr to hier(7) might not hurt there to explain /usr/local more generally.
There was a problem hiding this comment.
You are correct in your assessment, and in general I agree. However I believe we should not be overly-hospitable when it comes to enumerating all possible edge-cases that differ from the default/general case; eventually it will harm the clarity of the documentation.
For example, it is important that we maintain the functionality of LOCALBASE within all of our system tools and infrastructure. But you will find many man pages simply use a prefix of /usr/local/, as this is the default value. It should be understood by the intermediate user who wishes to tweak LOCALBASE (for whatever reason) that this translation is their responsibility.
Same goes for pkgsrc or openpkg (I personally had never heard of the latter before). These are supported use-cases, but not preferred or advertised in the way that pkg(8) is the standard method (or Tier-1 supported by FreeBSD). We cannot fully account for their usage in our documentation.
That said, here is my suggested wording for this particular case:
default location of configuration files for locally installed software (e.g. via pkg(7))
I have to say the descriptions in hier(7) are not particularly illuminating w.r.t. any of the alternative use-cases you brought up.
There was a problem hiding this comment.
I am willing to make this change, however I think this is a lot of redundancy, which is less straightforward and thus can be confusing, or sound less authorative. I don't know if I'm explaining it right but parenthesis drops the readers confidence interval.
I agree with the "not being overly hospitable arguement". Every single thing can be configured to do absolutely whatever you want even if it won't even work that way.
The design is that cfg for base software goes in /etc/, and cfg for installed software goes /usr/local/etc/.
Does 50 years of unix with now over 40k pkgs have a few weird corner cases that defy any attempt to make a terse, precise statement about how it works? Of course.
But does that mean the manual shouldn't tersely explain the design?
Let me chew on this a bit more.
| .It Pa /etc/ | ||
| location of most base system configuration files | ||
| .It Pa /usr/local/etc/ | ||
| location of installed component configuration files |
There was a problem hiding this comment.
You are correct in your assessment, and in general I agree. However I believe we should not be overly-hospitable when it comes to enumerating all possible edge-cases that differ from the default/general case; eventually it will harm the clarity of the documentation.
For example, it is important that we maintain the functionality of LOCALBASE within all of our system tools and infrastructure. But you will find many man pages simply use a prefix of /usr/local/, as this is the default value. It should be understood by the intermediate user who wishes to tweak LOCALBASE (for whatever reason) that this translation is their responsibility.
Same goes for pkgsrc or openpkg (I personally had never heard of the latter before). These are supported use-cases, but not preferred or advertised in the way that pkg(8) is the standard method (or Tier-1 supported by FreeBSD). We cannot fully account for their usage in our documentation.
That said, here is my suggested wording for this particular case:
default location of configuration files for locally installed software (e.g. via pkg(7))
I have to say the descriptions in hier(7) are not particularly illuminating w.r.t. any of the alternative use-cases you brought up.
intro(5) overhaul, key features:
Terse justifications are in the commits themselves.
Cc @llfw
Test Plan:
After verifying this commit contains no malicious syntax,
please download this file and read it in man(1).