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 <mhorne063@gmail.com>
| .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.
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).