freebsd
builtin.1: Rewrite including keybindings
Rewrite including keybindings, in the style and semantic density of the original bsd manual.
How to test:
Please read this rendered page splitscreen with the former. Try them in MANWIDTH=59 and 80, since some people use narrower consoles.
Try searching for the builtin commands in the respective shell manual pages. Verify that the information I determined was misfiled here is contained there.
Read intro and hier for comparison and consider if this is in the design philosophy and spirit of of the UNIX manual.
Try using the keybindings. Consider if they're sorted well or if sorting could be improved, or if I'm missing any of them.
Please also let me know any ideas to improve my doc testing methodology.
Cc @bsdimp, @bsdbcr, @mhorne, @delphij
There are parts of this pull request that are clearly welcomed (chiefly the key bindings, although I do not fully understand why have them in the built-in manual).
Others, I tend to think are removing vital information.
For example, what is a built-in?
Shell built-in [sic] commands are commands that can be executed within the running shell's process...
Where is this information in the proposed version? It looks like the proposed manual page assumes the reader knows this information beforehand.
From the Open Group (https://pubs.opengroup.org/onlinepubs/9799919799/):
The term "built-in" implies that there is no need to execute a separate executable file because the utility is implemented in the shell itself.
The removal of the names in the manual page: technically, the MLINKS would have to be removed as well? But this would make difficult for a reader to find a specific built-in, or to even know if it is one.
Whereas, currently, this page can be considered the entry-point of these functions from a reader's perspective.
Regarding suggestions about how to improve your doc testing methodology, what I do is check out the other BSDs (primarily NetBSD and OpenBSD) as well as the Open Group Specifications, and why not, Linux man pages if applicable. Luckily, I'm not a doc committer.
Another suggestion would be to "steal" good initiatives from these aforementioned projects, for example, if you open NetBSD's manual page (https://man.netbsd.org) you'll be greeted with a table of contents of all the manual page sections. IMO, this is more inviting than just a search box, but I may just be old fashioned.
Overall, I applaud the attitude, I might just need more time to chew on this proposed change.
The removal of the names in the manual page: technically, the MLINKS would have to be removed as well?
The point of the page is completely defeated if removing the MLINKS. This is an area where we bend the rules here all the time. I've taken to calling it "shadow mlinking". It makes the page look clean and straightforward.
What is this page about? You search the manual for a shell builtin like echo, and you get this page telling you "hey, that's actually not its own command, that command is part of your shell, so you need to look there for an explanation of what it does. Here's a real quick table of what is where to be sure."
Overall, I applaud the attitude, I might just need more time to chew on this proposed change.
This is a huge rewrite, so it's quite shocking, especially to src people who are very used to comparing the added to the removed line. I'm not expecting or even wanting this in this year (although it would be quite nice).
However, if you have time for manual pages, I'm scared that introducing explained search flags into the introduction to the manual will get skipped over this release cycle, and then I will spend a lot of extra time explaining it to new users when I already wrote it two months ago.
Shell built-in [sic] commands are commands that can be executed within the running shell's process...
That statement was an overgeneralization to begin with (subshells would like a word) and then didn't age well. The page immediately went off the course of the core focus of this page and began going off into the weeds disclaiming this statement. While it's doing so, we're loosing the reader with OT. This page is about "you have searched for manual page on a command which is actually part of your shell. You need to read the manual for your shell to see how that command works". And, that also includes process control.
not sure the state, but @concussious is a committer now and should land / close / etc
Mitchel said he needed more time to reflect. I am very proud of this and think it's very good. I considered it for a long time, and decided this page is cluttered by many things which are explained in where they belong in the respective shells manuals. This change removes no information from the overall manual.
This change is an important step in my effort to get the correct information in the correct place. People need to read the manual for their shell to understand how it works. Information architecture. Maintainability.
I think this is a very good thing, and I'm very proud of it.
Again, I think this drastically improves the accessibility of this page, removes no information from the manual, and improves the organization of the manual.
Therefore, if there is no objection, I intend to merge this in one week.