From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout.scc.kit.edu (scc-mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p62Kbg3O018889 for ; Sat, 2 Jul 2011 16:37:44 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1Qd6we-0007Nr-Tk; Sat, 02 Jul 2011 22:37:40 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1Qd6we-0002oW-TM; Sat, 02 Jul 2011 22:37:40 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1Qd6we-0007nj-SG; Sat, 02 Jul 2011 22:37:40 +0200 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1Qd6we-0006fY-JT; Sat, 02 Jul 2011 22:37:40 +0200 Date: Sat, 2 Jul 2011 22:37:40 +0200 From: Ingo Schwarze To: Paul Onyschuk Cc: discuss@mdocml.bsd.lv Subject: Re: Lengthy documentation in mdoc Message-ID: <20110702203740.GA1292@iris.usta.de> References: <20110702213626.dda0b983.blink@bojary.koba.pl> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20110702213626.dda0b983.blink@bojary.koba.pl> User-Agent: Mutt/1.5.21 (2010-09-15) Hi Paul, Paul Onyschuk wrote on Sat, Jul 02, 2011 at 09:36:26PM +0200: > Hello, I'm looking into rewriting THE [1] (The Hessling Editor) > documentation in mdoc (for mandoc in mind). Some explanations: > > Current state: > - THE documentation contains plain text files converted to html/pdf > (bad quality output) > - man page isn't useful at all > > Why mandoc? > - one format and multiple outputs with better quality > - documentation in one place (semi-formats like markdown with pandoc > or POD only complicates situation) Yes. I think that rationale makes sense, and mdoc(7) is a good tool for the task at hand. > Before jumping at me (Why you use tool that needs so much > documentation!?), be aware that THE comes from very different > culture - mainframes. Well, most editors have lots of interactive commands, even nvi and mg look similar. Besides, we want writing documentation to be simple and efficient even for tools that are themselves complicated. > The good thing is that every command [2] in documentation has very > man-page-like structure. Actually, that doesn't help much, unless... > So what's the problem? As I mentioned before, THE documentation is > mainly plain text, but it's about ~12k lines long [3]. > > I looked into multiple scenarios: > - splitting man page like zsh ... you go that way, which i don't recommend at all. It causes many problems. For example, you can't search in a manual like that, and moving about it is a pain in general. In OpenBSD, we even lumped openssl(1) all into one page when importing it from upstream. > - custom section like perl modules e.g. 3pm Well, the stuff in 3p is prepared with pod2man(1) and man(7); you shouldn't use that as a model for modern documentation. It works, but it is not nice. > - one big man page Yes, i think that will work. > And third options seems like best of worst. Navigation of big man page > can be problematic, but splitting it up doesn't help at all. Adding > another section to man pages isn't option at all. Right. Do not mess with sections, like (1THE). That would cause different issues with different operating systems and different roff and man implementations. > Another reason for one fat page, are documentation references as seen in > ADD command. I came up with idea of abusing sub-sections (every command > is sub-section) and using Sx macro for references. Yes, you can do that, i wouldn't call that abuse. Look at mdoc(7) for an example on how to use .Ss/.Sx for commands. > Example template would look more-or-less like this: > >> .Sh COMMANDS >> (...) >> .Ss ADD >> add blank line I'd probably convert this line to a complete sentence and move it to the beginning of the description, or just drop it if its already there. A full mdoc(7) page needs an .Nd, but a mere .Ss subsection doesn't. >> .Bl -tag -width 1m >> .It Syntax: >> .Cm Add Op Ar n >> .It Description: >> If >> .Sx SET NEWLINES >> is set to ALIGNED, the cursor is positioned >> (...) >> .It Compatibility: >> XEDIT: Compatible. >> .Pp >> KEDIT: Compatible. >> .It Default: >> 1 >> .It See Also: >> .Sx SOS ADDLINE >> .It Status: >> Complete >> .El That looks reasonable. Maybe it's a bit verbose, it could be cut down, but that's merely a matter of style, like: .Sh COMMANDS .Ss ADD Syntax: .Cm Add Op Ar n .Pp Insert .Ar n blank lines after the current line, if issued from the command line, or after the focus line, if issued from the file area or prefix area. By default, one single line is added. .Pp The .Cm Add command is compatible with XEDIT and KEDIT. .Pp See also .Sx SOS ADDLINE . Sometimes less markup and formal structure is easier on the eye. I'm not sure "Status: Complete" needs to be mentioned at all. In a manual, that should go without saying. Of course, you should mention the limitations if something is *not* fully implemented. > This way html output and so on will use sub-sections references as > links. Although this requiers few dozen sub-sections (I wouldn't be > surprised if number is 200+). No problem with that. > So end users will enjoy (?) one fat man page, but developers will work > on smaller files. Every command will be separate file "cated" by > makefile at build time. It easier to work on smaller chunks. Maybe. As you like. :) But working with a single file like ksh.1 is not that hard, either. > I'm looking for opinions from people with more experience in working > with mdoc. Maybe there is better solution for this? Am I creating > another man-page abomination or using wrong tool? No. All this sounds quite sane. > Overall I wanted to ask this questions, before actual work. > > btw. Thank you Kristaps and Ingo for creating/maintaining great tool > and everyone else involved with mandoc. Apologies for my "english" > writing. You are welcome! (And nothing is wrong with your English, as far as i can see.) Have fun with mandoc, Ingo > [1] http://hessling-editor.sourceforge.net/ > [2] http://hessling-editor.sourceforge.net/doc/comm/ADD.html > [3] http://blinkkin.github.com/the/the.man -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv