A new approach for BSD man pages

T

tinkerdaemon

Hi,

I want to modernize the man pages of the BSD systems.

In my opinion the modern man pages should be organized under the use cases of the tools. Today they are organized following the options and commands of the tools. For example the ls man page shows the options -a and -A and so on. I would like to make these entries "Show all files and directories even those starting with ." and "Do not list implied . and ..".

This makes it possible to organize the man pages in files and directories with the use case as name and entries. So you can link every use case with alternative tools where appropriate.

Then I would like to make HTML5 the main development platform for the man pages. Every BSD platform has at least a text based browser. HTML5 is known to much more people than Troff and Nroff etc. One can use modern layouts to present alternative examples for every tool and use case etc.

At last - as far as I planned it for now - there should be for every use case a required section of examples and alternatives. This is in my mind a must for man page as the standard use of the tool should be shown for someone learning from the man page.

Tell me what you would like to make better in the man pages system.
 
The man pages are meant to be references, not tutorials. I don't quite understand what you mean by organizing them by files and directories with use cases. Wouldn't the user have to search by the exact stated use case, which they might phrase differently?

Both groff(1) and the newer mandoc(1) can produce HTML output. mandoc(1)'s is more useful.

I say that examples should be almost a requirement for a man page. The trick there is that too many examples can hide detail rather than show it. The dividing line depends on the utility.
 
Have you had a look at https://www.freebsd.org/cgi/man.cgi? I think it works well. The references to related man pages are available as link, too. Having examples and alternatives is good. A different challange is to find out which tool is available and which is best for which case. Fortunately the base system and the port collection offers a huge choice. There are many ways to dig.

Please excuse me if I have misunderstood your goal.
 
tinkerdaemon said:
In my opinion the modern man pages should be organized under the use cases of the tools ... there should be for every use case a required section of examples and alternatives.
Click to expand...

This is Unix. Programs are intended to be simple so that they might be chained together to achieve different results. The use cases for each program are therefore infinite, changing with the context in which the program is used and the goal the user wishes to achieve. On its own, ls shows all visible files in the current directory. With the -a flag, ls shows all files including hidden files in the current directory. But when combined with wc, I can get a multitude of information about the current directory that changes depending on the option flags I pass to ls, all of which would be useful in different contexts:

Code: 
# Number of visible files in top-level $HOME directory:
 ls | wc -l
  9

# Total number of files in top-level $HOME directory:
 ls -a | wc -l
  76

# Number of visible files in the complete $HOME directory tree:
 ls -lR | wc -l
368415

# Total number of files in the complete $HOME directory tree:
 ls -laR | wc -l
399443

Each piece of information, derived from the same program(s), is useful in a different context and use case. I would probably take the final result and pass it to yet another program, and write a script that tied them all together--a different script for each thing I wanted to do. The number of pages necessary to document every use case would be immense--quite likely several gigabytes of data dedicated just to documentation most people would never find the least bit useful. It would also forever be incomplete. So logically you'd have to draw the line somewhere, but where? Who decides what use cases get documented and why? Right now the answer is "No one decides that--we just document the programs, not every little thing people might conceivably do with them."
 
You must log in or register to reply here.
Back
Top