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 p62Mw6DV010132 for ; Sat, 2 Jul 2011 18:58:07 -0400 (EDT) Received: from [10.0.20.128] (helo=desant) by psyche.piasta.pl with esmtpa (Pocztex KoBa) (envelope-from ) id 1Qd98U-0006xc-Rg for discuss@mdocml.bsd.lv; Sun, 03 Jul 2011 00:58:05 +0200 Date: Sun, 3 Jul 2011 00:58:06 +0200 From: Paul Onyschuk To: discuss@mdocml.bsd.lv Subject: Re: Lengthy documentation in mdoc Message-Id: <20110703005806.4daed28e.blink@bojary.koba.pl> In-Reply-To: <20110702203740.GA1292@iris.usta.de> References: <20110702213626.dda0b983.blink@bojary.koba.pl> <20110702203740.GA1292@iris.usta.de> 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-03 00:58:05 On Sat, 2 Jul 2011 22:37:40 +0200 Ingo Schwarze wrote: > > 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 isn't more complicated than vi/emacs, it's just diffrent and less popular. I don't have problems with using nvi/mg. I'm more interested in editors history and why they become what is know today. This [1] isn't 100% accurate, but gives you idea about vi/emacs/xedit. > > 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. > You're probably right here. Moving this to beginning, means it can also be used as some kind of index. > > That looks reasonable. Maybe it's a bit verbose, it could be > cut down, but that's merely a matter of style, like: > > 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. > That is very useful input, less is more :] > > Maybe. As you like. :) > But working with a single file like ksh.1 is not that hard, either. > Right now documentation is embedded into the source as comments e.g.: > > /* > **man-start** > (...) > **man-end** > */ > Makefile (grep etc) is used to create plain text and then html/pdf. Most docs are in files: "comm1.c comm2.c comm3.c comm4.c comm5.c commset1.c commset2.c commsos.c". I just want to maintain this structure by keeping seprate mdoc files e.g. "comm1/add.1.in" - it seems it easier to keep them up to date this way (changes in comm1.c means that you need update doc file in comm1/*). On Sat, 02 Jul 2011 23:14:44 +0200 Kristaps Dzonsons wrote: > > 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. > Manual isn't the problem. Advocating mdoc/mandoc is the main issue, just look at this [2]. Most selling points were obtained from BSDCan presentations. Those informations aren't on mandoc web page and reaching them isn't easy. Moreover mandoc can compete with tools other than man page and roff specific (groff etc) in my opinion. btw. Kristaps can you share slides from BSDCan? Man pages tutorial on bsd.lv [3] is useful, still it's far from perfect. I started from there and AFAIK this link was shared on Stack Overflow and other sites on few occasions. > 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. After rewriting THE documenation I planed to play with CSS/javascript. Folding features for section/sub-sections in html shouldn't be much trouble e.g. (current output has nice CSS structure): - click [+] to unfold section COMMANDS, then [+] ADD command Even creating preseantion slides (omitting pictures) should be easy if default CSS/HTML output is sane enough. > 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... I thinked about using perl-modules-like sections just for this reason. mandoc-tools (mandoc-cgi few days ago) is so much better than any tool available right now, that I really thinked about splitting THE documentation in separate man pages. Option to search just specific man page? Dunno... > Anyway, enjoy! I'm Textile [4] fan and in my humble opinion mdoc is lightweight markup of documentation world. I enjoyed it to very last drop ;) I'm subscribed to the list, so no need for CC-ing mails to me directly. [1] https://github.com/blinkkin/the/wiki/Editors-and-keyboards [2] https://github.com/blinkkin/blinkkin.github.com/wiki/man-vs-mdoc [3] http://manpages.bsd.lv/ [4] http://en.wikipedia.org/wiki/Textile_(markup_language) -- Paul Onyschuk -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv