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 p62JaQvD002640 for ; Sat, 2 Jul 2011 15:36:27 -0400 (EDT) Received: from [10.0.20.128] (helo=desant) by psyche.piasta.pl with esmtpa (Pocztex KoBa) (envelope-from ) id 1Qd5zK-000625-Bc for discuss@mdocml.bsd.lv; Sat, 02 Jul 2011 21:36:24 +0200 Date: Sat, 2 Jul 2011 21:36:26 +0200 From: Paul Onyschuk To: discuss@mdocml.bsd.lv Subject: Lengthy documentation in mdoc Message-Id: <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-02 21:36:24 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) Before jumping at me (Why you use tool that needs so much documentation!?), be aware that THE comes from very different culture - mainframes. The good thing is that every command [2] in documentation has very man-page-like structure. 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 - custom section like perl modules e.g. 3pm - one big man page 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. 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. Example template would look more-or-less like this: > .Sh COMMANDS > (...) > .Ss ADD > add blank line > .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 > (...) > .Sh OPTIONS > .Ss SET NEWLINES > (...) 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+). 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. 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? 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. [1] http://hessling-editor.sourceforge.net/ [2] http://hessling-editor.sourceforge.net/doc/comm/ADD.html [3] http://blinkkin.github.com/the/the.man -- Paul Onyschuk -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv