On Saturday, 25 February 2017 10:16:37 PYST Janne Johansson wrote: > 2017-02-25 9:45 GMT+01:00 Currell Berry <[email protected]>: > > 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
I second both - OP and comment. -- Eike Lantzsch ZP6CGE “Do you actually know what you are reading?” He said: “Really, how could I ever do so unless someone guided me?” ... (Acts 8:30, 31)
