2017-02-25 9:45 GMT+01:00 Currell Berry <currellbe...@gmail.com>: > Is feedback / are patches solicited for man-pages in order to improve > their usability to average users (even if this were to make them > somewhat less formal in nature)? > > I find the openbsd man pages very useful, but I do run across things > which I cannot figure out from the man pages and/or faq. Often I will > then do a web search to look for an answer to my dilemma. When I find > the answer, I often wish that a piece of information had been included > in the relevant man pages and/or faq which would have prevented me > needing to search through the internet. Often this piece of information > is a usage example. > > Three recent examples for me were: > 1. the xorg.conf manual page does not say anything about specifying > resolution (rough answer -- the mode name generally identifies resolution > by > using a string such as "1024x768". there are various preset modes or > you can create your own). > > 2. The openbsd disk setup FAQ does not really tell you to use newfs > after you have used fdisk and disklabel. It tangentially mentions newfs > in the portion about "encrypting external disks" and in the answer to > the prompt "Why does df tell me I have over 100% of my disk used". I > think perhaps newfs as the next step in the disk setup process could be > mentioned in the FAQ, and also that maybe the disklabel utility man page > could > include a link to or small comment about newfs. > > Yes, the chapter Partitions and filesystems
of faq14 should actually talk about filesystems also, and probably mention newfs while there, but it almost exclusively discusses partitions and partitioning. > 3. Many of the login.conf resource limits appear to be per process, but > the man page does not in general differentiate the limits that are per > user and per-process. So, for instance, cputime is identified as "CPU > usage limit" but I cannot know without prior knowledge or searching > whether this is enforced per-process or per-user. > > I think a short notice on how it is applied could well fit into that manpage, if kept brief. You would have to be careful not to have the same information typed down in various ways also in limit descriptions (in shell manpages mostly for ulimit) and setrlimit(2). > So, in all of these cases, there is no error in the documentation, it > just doesn't hold the user's hand very much. Does OpenBSD want man-page > patch submissions which attempt to improve the usability of the > man-pages? If so, > where should such patches be submitted? > > Thanks, > Currell > -- > Currell Berry > http://www.cvberry.com > > -- May the most significant bit of your life be positive.
