From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-1.sys.kth.se (smtp-1.sys.kth.se [130.237.32.175]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p62LEuQr015740 for ; Sat, 2 Jul 2011 17:14:57 -0400 (EDT) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-1.sys.kth.se (Postfix) with ESMTP id 0AB64154134; Sat, 2 Jul 2011 23:14:51 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-1.sys.kth.se ([130.237.32.175]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id eWOls5-feutj; Sat, 2 Jul 2011 23:14:47 +0200 (CEST) X-KTH-Auth: kristaps [89.158.117.88] X-KTH-mail-from: kristaps@bsd.lv Received: from macky.local (89-158-117-88.rev.dartybox.com [89.158.117.88]) by smtp-1.sys.kth.se (Postfix) with ESMTP id 1D151154129; Sat, 2 Jul 2011 23:14:45 +0200 (CEST) Message-ID: <4E0F8A44.7070505@bsd.lv> Date: Sat, 02 Jul 2011 23:14:44 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.18) Gecko/20110616 Thunderbird/3.1.11 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: discuss@mdocml.bsd.lv CC: Ingo Schwarze , Paul Onyschuk Subject: Re: Lengthy documentation in mdoc References: <20110702213626.dda0b983.blink@bojary.koba.pl> <20110702203740.GA1292@iris.usta.de> In-Reply-To: <20110702203740.GA1292@iris.usta.de> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit >> 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, Paul, Ingo's pretty much said it all. If you have any questions, don't hesitate to ask on the list---and do feel especially free to voice any questions regarding the mdoc(7) manual. When it comes to generating HTML output, speak up if you have ideas for exploiting inter-page linkage. For example, I had wanted to generate elements for the section and subsections of a document. But browsers don't usually account for this, so it would be wasted effort (pity!). Another idea is an `-Otoc' option (or whatever) that would cause -Thtml to generate a table of contents along with the page output. OpenBSD's man.cgi does this now at the bottom of the page; however, I think this is kind of ugly and unwieldly for large documents. Come to think of it, a nice feature for http://mdocml.bsd.lv/mandoc-cgi/ would be jumping to a table of contents and/or semantic index (a la ptx) for individual manuals... hmmm... Anyway, enjoy! Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv