The intro(9) man page is outdated, with a last modified date of 1995(!). The page contains a few general programming recommendations and a link to style(9). Beyond this it fails to provide any real introduction to this section of documentation. While imperfect, section 9 is the most comprehensive set of documentation for the FreeBSD kernel source code that exists. This man page has the potential to be a useful landing page for navigating and discovering this resource. A complete rewrite of this page is in order, with the following goals/principles: - Provide more detailed high-level introduction to this documentation set; describe purpose, authors & audience, and expectations regarding coverage, level-of-detail, and accuracy - Include cross-references to as many section 9 pages as reasonable. This improves their discoverability - Group links by subsystem/domain. NetBSD's intro(9) page is a good example of this [1] I have begun this rewrite, so this PR is self-assigned and mainly for tracking purposes. Feedback on what should be usefully included in the new page is welcome. [1] https://man.freebsd.org/cgi/man.cgi?query=intro&apropos=0&sektion=9&manpath=NetBSD+9.3&arch=default&format=html
Perfect! Now I know where to point people when they don't like my code formatting :-) Oooh it's written in intro(9) that I don't have to care about style(9) really .... > - Include cross-references to as many section 9 pages as reasonable. This improves their discoverability +1 Are you making a differential revision for this? Maybe you could start with the same sections NetBSD use, and then just fill in new stuff for FreeBSD? --HPS
I've added a fairly complete draft of the new page to Phabricator, D41104. If you are interested in reviewing please add yourself.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=84f9f2c5cf7841fffc03ccb1833814892ae15132 commit 84f9f2c5cf7841fffc03ccb1833814892ae15132 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-08-03 13:48:15 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-08-03 14:07:41 +0000 intro(9): rewrite from scratch This page has existed as a placeholder since its creation in 1995. It does not provide a useful introduction to the content in this section. Reimagine it as a top-level overview page containing brief descriptions and links to existing pages in section 9. It is roughly organized into sub-sections, grouped by topic or subsystem. In other words, the page is meant to function as a map to other content. There is a balance to be found here between providing as many links as possible and keeping the page concise and searchable. In general the aim is to reference pages which provide the best entry point to a particular topic. For example, a link is given to locking(9), but not to the specific lock pages such as mutex(9) or rwlock(9). NetBSD has done something similar with their intro(9), so some inspiration has been taken from there, although their content doesn't align that closely with what we have. I have done a thorough review of our existing pages and formed these subsections around them, but they are meant to evolve. PR: 270481 Reviewed by: imp, emaste MFC after: 3 weeks Relnotes: yes Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D41104 share/man/man9/intro.9 | 594 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 504 insertions(+), 90 deletions(-)
A great improvement, thanks. <https://github.com/freebsd/freebsd-src/pull/813> includes one correction, and suggests a few other minor changes.
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=5a0c410787b8b2f92a0c3f6126c95ffe34de344c commit 5a0c410787b8b2f92a0c3f6126c95ffe34de344c Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-08-03 13:48:15 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-09-11 22:42:15 +0000 intro(9): rewrite from scratch This page has existed as a placeholder since its creation in 1995. It does not provide a useful introduction to the content in this section. Reimagine it as a top-level overview page containing brief descriptions and links to existing pages in section 9. It is roughly organized into sub-sections, grouped by topic or subsystem. In other words, the page is meant to function as a map to other content. There is a balance to be found here between providing as many links as possible and keeping the page concise and searchable. In general the aim is to reference pages which provide the best entry point to a particular topic. For example, a link is given to locking(9), but not to the specific lock pages such as mutex(9) or rwlock(9). NetBSD has done something similar with their intro(9), so some inspiration has been taken from there, although their content doesn't align that closely with what we have. I have done a thorough review of our existing pages and formed these subsections around them, but they are meant to evolve. PR: 270481 Reviewed by: imp, emaste MFC after: 3 weeks Relnotes: yes Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D41104 (cherry picked from commit 84f9f2c5cf7841fffc03ccb1833814892ae15132) share/man/man9/intro.9 | 594 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 505 insertions(+), 89 deletions(-)