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.
