Theo Buehler writes: > On Sat, Feb 25, 2017 at 07:01:30AM -0300, Eike Lantzsch wrote: >> On Saturday, 25 February 2017 10:16:37 PYST Janne Johansson wrote: >> > 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). > > Most of the manuals in xenocara/ are not ours and we don't usually > modify them a lot. You may want to contact upstream: > https://www.x.org/wiki/DeveloperStart/ > >> > > 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. > > Sounds totally reasonable, a short sentence or two on newfs certainly > wouldn't hurt... I suggest you send a patch to tech@ and tj and I will > consider it. > >> > > 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? > > Patches (including documentation) are best sent to the tech@ mailing > list.
I will subscribe to tech@ and look to submit some doc patches in the future. Are there any guidelines anywhere on what we are going for in a man page? If not is there a page which is very good and can be held up as a standard? -- Currell
