From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from psyche.piasta.pl (psyche.piasta.pl [83.175.144.5]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p65COoET031786 for ; Tue, 5 Jul 2011 08:24:52 -0400 (EDT) Received: from [10.0.20.128] (helo=desant) by psyche.piasta.pl with esmtpa (Pocztex KoBa) (envelope-from ) id 1Qe4gH-0005JG-4q for discuss@mdocml.bsd.lv; Tue, 05 Jul 2011 14:24:46 +0200 Date: Tue, 5 Jul 2011 14:24:49 +0200 From: Paul Onyschuk To: discuss@mdocml.bsd.lv Subject: Re: Lengthy documentation in mdoc Message-Id: <20110705142449.1ee0f969.blink@bojary.koba.pl> In-Reply-To: <20110702213626.dda0b983.blink@bojary.koba.pl> References: <20110702213626.dda0b983.blink@bojary.koba.pl> X-Mailer: Sylpheed 3.1.1 (GTK+ 2.10.14; i686-pc-mingw32) X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Invalid-HELO: HELO is no FQDN (contains no dot) (See RFC2821 4.1.1.1) X-Sender-Verify: SUCCEEDED (sender exists & accepts mail) X-Date: 2011-07-05 14:24:46 I followed feedback provided by Ingo. Here is small preview of what has been done [1] (mdoc source is not yet ready for sharing). Still it is very early work, so grammar mistakes are common and formating is not finished. Some reasoning: - Describe status only if command is not complete. - Provide information about XEDIT/KEDIT only if command is incompatible or has different behavior in former. - Write about default behavior in description. - Avoid describing command by name (e.g. "The BACKWARD command scrolls ..."). This way command references are much less verbose and easier to read. I'm not sure about one thing: enclosing commands in angle brackets. I started with this: > > Syntax: > .Ic CURsor Ar Column > And it didn't work out - some commands had more than one version. Good exmaple is CURSOR [2]. In original, structure used was like "command, command... description, description...". My version uses "command, description ..." layout to gain some readability, but this way distinguishing separate commands can be problematic. "Syntax:" every two line doesn't help, so I came up with idea of using angle brackets. I also tried using blocks with offset for commands and then for description. Longer commands are unnecessary splitted across multiple lines and offset for description is just poor idea. Maybe it's totally wrong approach, so I'm looking once again for feedback. As for other things, Rexx variables as seen in ALERT and DIALOG, doesn't belong in commands listing. Currently most of them can be found in query section [3]. Personally I think that it is the only part (Rexx variables), that can be safely moved to separate man page. Those variables requires knowledge of Rexx, so rexx(1) and other man pages are probably needed anyway. Some commands (like ALL) provides also examples, but this is small problem. They can be moved to EXAMPLES later if needed. As for mdoc(7), I feel much more comfortable with sources right now, than few days ago. One thing I'm missing is something like style(9) just for mdoc. I found myself looking into other man pages on more than one occasion. Many times I was just looking for improvements in source readability (style of comments and so on), not formating which is well explained in mdoc(7). [1] http://blinkkin.piasta.pl/the/index.html [2] http://hessling-editor.sourceforge.net/doc/comm/CURSOR.html [3] http://hessling-editor.sourceforge.net/doc/misc/query.html -- Paul Onyschuk -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv