From owner-freebsd-questions@freebsd.org Thu Oct 12 19:45:52 2017 Return-Path: Delivered-To: freebsd-questions@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id DB095E33066 for ; Thu, 12 Oct 2017 19:45:52 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from mailrelay11.qsc.de (mailrelay11.qsc.de [212.99.187.252]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "*.antispameurope.com", Issuer "TeleSec ServerPass DE-2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 47B5564B11 for ; Thu, 12 Oct 2017 19:45:51 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from mx01.qsc.de ([213.148.129.14]) by mailrelay11.qsc.de; Thu, 12 Oct 2017 21:45:49 +0200 Received: from r56.edvax.de (port-92-195-127-141.dynamic.qsc.de [92.195.127.141]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx01.qsc.de (Postfix) with ESMTPS id 2C10A3CBF9; Thu, 12 Oct 2017 21:45:47 +0200 (CEST) Received: from r56.edvax.de (localhost [127.0.0.1]) by r56.edvax.de (8.14.5/8.14.5) with SMTP id v9CJjlhp001966; Thu, 12 Oct 2017 21:45:47 +0200 (CEST) (envelope-from freebsd@edvax.de) Date: Thu, 12 Oct 2017 21:45:47 +0200 From: Polytropon To: Yuri Pankov Cc: freebsd-questions@freebsd.org, "Sijmen J. Mulder" Subject: Re: Should I use mdoc for user programs? Message-Id: <20171012214547.2ceef598.freebsd@edvax.de> In-Reply-To: <696e0fb1-7cbb-31d2-2105-8166a4c3d53e@gmx.com> References: <20171012200941.49fed687.freebsd@edvax.de> <696e0fb1-7cbb-31d2-2105-8166a4c3d53e@gmx.com> Reply-To: Polytropon Organization: EDVAX X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-cloud-security-sender: freebsd@edvax.de X-cloud-security-recipient: freebsd-questions@freebsd.org X-cloud-security-Virusscan: CLEAN X-cloud-security-disclaimer: This E-Mail was scanned by E-Mailservice on mailrelay11.qsc.de with 7B7AF6A3598 X-cloud-security-connect: mx01.qsc.de[213.148.129.14], TLS=1, IP=213.148.129.14 X-cloud-security: scantime:.1663 X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 12 Oct 2017 19:45:53 -0000 On Thu, 12 Oct 2017 21:39:53 +0300, Yuri Pankov wrote: > On Thu, 12 Oct 2017 20:09:41 +0200, Polytropon wrote: > > On Thu, 12 Oct 2017 16:18:28 +0300, Yuri Pankov wrote: > >> On Thu, 12 Oct 2017 11:02:49 +0200, Sijmen J. Mulder wrote: > >> [...] > >>> I noticed that the required .Os macro (man 7 mdoc) outputs "FreeBSD > >>> General Commands Manual" which does not seem appropriate. > >> > >> It's not about the .Os macro, rather it's man-section-to-name mapping > >> done by the formatter used, i.e. when using mandoc(1), on FreeBSD > >> section 1 man pages would say "FreeBSD General Commands Manual", on > >> illumos exactly the *same* man page would say just "User Commands" (for > >> mandoc this can be customized editing one of the source files currently). > > > > According to "man mdoc", it's easy to redefine .Dt at the beginning > > of the document (just like .Dt or Dd). > > Indeed, my answer was more about that output shouldn't stop the OP from > using mdoc. And redefining the section name rarely serves any purpose; > if you absolutely need it, go with a new section (yes, I know it's bad). This is possible, but if you can, use the established categories. Binaries (programs in general) to section 1, files to section 5, and so on. Ports-supplied manpages go to /usr/local/share/man anyways (instead of the OS location at /usr/share/man). Using "custom sections" like "3X" (found in "man curs_attr", for example) is possible as well. To avoid confusion with OS-provided tools, it will probably help to change the information in the header and footer which mdoc generates automatically when the default macros are being used. With "man mdoc" and the examples in /usr/share/examples/mdoc usable templates can be easily created. A nice example is "man mplayer", where the header and footer are: MPlayer(1) The Movie Player MPlayer(1) The MPlayer Project 2009-03-25 MPlayer(1) The macros at the beginning of the manpage allow conveniently changing anything that's needed - _if_ it is required or desired. Nothing is hidden, nothing is revealed. ;-) -- Polytropon Magdeburg, Germany Happy FreeBSD user since 4.0 Andra moi ennepe, Mousa, ...