From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id oARIj6ET015872 for ; Sat, 27 Nov 2010 13:45:08 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1PMPlg-0006ii-59; Sat, 27 Nov 2010 19:45:04 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1PMPlg-0004re-3a; Sat, 27 Nov 2010 19:45:04 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1PMPlg-0008Vr-1x; Sat, 27 Nov 2010 19:45:04 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1PMPlf-0004mO-Mx; Sat, 27 Nov 2010 19:45:03 +0100 Date: Sat, 27 Nov 2010 19:45:03 +0100 From: Ingo Schwarze To: jmc@openbsd.org Cc: discuss@mdocml.bsd.lv Subject: Where to put mandoc roff documentation? Message-ID: <20101127184503.GA27534@iris.usta.de> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) Hi Jason, i'm looking for your advice regading the question how to organize mandoc roff documentation. By that term, i'm referring to man pages explaining: 1. Common features of the mdoc(7) and man(7) languages being common because they are actually features of the roff language - currently, there is quite some duplication. Topics include: - basic request and macro syntax - permitted input characters - comment syntax - predefined special characters and strings - predefined escape sequences, for example regarding text decoration - basics of whitespace handling - scaling widths - end-of-sentence spacing 2. Common macros being common because they are actually roff macros or even roff requests, for example: - .br - .sp 3. Low-level roff requests that are not mdoc(7) or man(7) macros, for example: - .de - .ds - .if - .ig - .nr - .rm - .rn - .so And also: - user-defined macros - user-defined strings 4. Common aspects of the usage of the mdoc(7) and man(7) languages being common because they do not depend on the language at all. Topics include: - manual sections - general advice about writing manuals In particular, running mandoc -Tlint on Perl, Xenocara, and typical ports manuals, i expect improving low-level roff support will be the focus of mandoc development in the near future. Hence, most of the new documentation to be written will probably be category 3, and perhaps some 2. I consider moving roff.7 from /usr/src/usr.bin/mandoc/ to /usr/src/share/man/man7/ and getting it ready for installation by moving documentation of the categories 1, 2 and 3 into it. But i'm not 100% sure whether all of this - with the exception of mandoc_char(7), of course - should really go into the same document. I'm also hesitant regarding the name. The current name roff(7) seems fitting on the one hand, because this document would indeed document features of the roff language, and nothing else. On the other hand, that name feels presumptuous, because we will hardly ever document the roff language as a whole, and because calling it roff(7) would hide the rather interesting roff(7) manual once we update our groff port to a recent version, see: http://www.manpagez.com/man/7/roff/ Yet on the other hand, even though that document is interesting, it is perhaps named badly and should be installed as roff_history(7), or not at all, because however interesting, it is not a real manual. Finally, i feel quite at a loss about what to do with category 4. Maybe move it to a manuals(7) manual, like the one Kristaps once started, and .Xr to it? Or leave it in mdoc(7), because that's where we send people writing new manuals, and point to it from man(7)? Or just maintain two copies for good? Thoughts? Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv