Bug 248562 - [meta] intro man pages: review, revamp, update
Summary: [meta] intro man pages: review, revamp, update
Status: In Progress
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: freebsd-doc (Nobody)
URL:
Keywords: needs-qa, tracking
Depends on: 84956 261349 270481
Blocks:
  Show dependency treegraph
 
Reported: 2020-08-09 20:38 UTC by Mina Galić
Modified: 2024-03-08 14:33 UTC (History)
7 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Mina Galić freebsd_triage 2020-08-09 20:38:00 UTC
the intro man pages are, upon installation recommend as one of the first man pages to read to familiarise oneself with a freebsd system

however, after reading them, we have, at best, familiarised ourself with a freebsd system from the 1990s

I don't believe that it's necessary for `intro(8)` to speak of

> Network related services like `inetd(8)` and `ftpd(8)` are also described.
Comment 1 Graham Perrin freebsd_committer freebsd_triage 2022-10-17 13:46:20 UTC
See also: <http://markmail.org/message/nlp6ahgbje42expx>


> The 2000s called. They want their intro(8) back.

– Pau Amma, New Year's Eve, 2021.
Comment 2 Pau Amma 2022-10-17 14:09:19 UTC
(In reply to Graham Perrin from comment #1)
Also known as https://lists.freebsd.org/archives/freebsd-doc/2021-December/001068.html
Comment 3 Mitchell Horne freebsd_committer freebsd_triage 2022-10-17 14:54:39 UTC
Hello,

I have some plans to update and revamp intro(9). I will create a separate bug for this when the time comes. Perhaps this one could become a tracking PR?

Cheers,
Mitchell
Comment 4 Graham Perrin freebsd_committer freebsd_triage 2022-10-17 15:25:11 UTC
(In reply to Mitchell Horne from comment #3)

> … Perhaps this one could become a tracking PR?

Yeah, let's do that now, before the twenty-second century calls. 

Mina: feel free to revert the status, keyword(s), etc., if you'd prefer a different approach. 

Thanks, and thanks.
Comment 5 Alexander Ziaee 2024-03-07 02:56:07 UTC
I started on intro(2) because making it pretty seemed straightforward, I think it's getting pretty good.

https://github.com/freebsd/freebsd-src/pull/1065

I don't know if I should add the internal kernel pseudoerrors mentioned in errno.h?

Any recommendations for intro(2)?

I'm feeling extremely insecure about realizing another typo while trying to sleep, and then force-pushing, and then github check fails telling me I ostensibly wasted the whole entire projects github compute bandwidth recompiling llvm for typo correction in a 28K man page.
Comment 6 Alexander Ziaee 2024-03-08 14:33:15 UTC
Here's what I've got so far for intro(1).

I want to update this page concisely without bloating or mangling it. It's previous state is extremely eloquent and concise, and I'd like to see that preserved.

https://github.com/freebsd/freebsd-src/pull/1136