From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailout.scc.kit.edu (mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id s5ECG5KY028682 for ; Sat, 14 Jun 2014 08:16:07 -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 1WvmsL-0008BF-2z; Sat, 14 Jun 2014 14:16:01 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1WvmsC-0002Sv-QC; Sat, 14 Jun 2014 14:15:52 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1WvmxX-00078P-6X; Sat, 14 Jun 2014 14:21:23 +0200 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1WvmsK-0000hA-OL; Sat, 14 Jun 2014 14:16:00 +0200 Date: Sat, 14 Jun 2014 14:16:00 +0200 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Cc: David Holland , Thomas Klausner Subject: Re: Extension for more general documents Message-ID: <20140614121600.GA27521@iris.usta.de> References: <20140613083536.GJ14438@danbala.tuwien.ac.at> 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: <20140613083536.GJ14438@danbala.tuwien.ac.at> User-Agent: Mutt/1.5.21 (2010-09-15) Hi Thomas, Thomas Klausner wrote on Fri, Jun 13, 2014 at 10:35:36AM +0200: > We'd really like to move away the documents in NetBSD's base system > from the groff -ms and -me macro sets to anything else that can be > easily converted to txt, html, and pdf. > > We already have mandoc in the base system and it supports these output > formats. So it seems to be a good candidate, and mdoc already provides > the formatting options we need (AFAIK). > > We probably would just need to add a mode to mandoc where it doesn't > insist on a man page header and instead supports some article > information like a title. Uh, oh. Indeed i misunderstood this request completely. So let's look at how the csh document currently looks like, as an example: ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 ----- ischwarze@isnote $ groff -ms -Tascii -P-c tabs csh.* An Introduction to the C shell William Joy (revised for 4.3BSD by Mark Seiden) Computer Science Division Department of Electrical Engineering and Computer Science University of California, Berkeley Berkeley, California 94720 ABSTRACT Csh is a new command language interpreter for UNIX(R) systems. It incorporates good features of [...] Introduction A shell is a command language interpreter. Csh is the name of one particular command interpreter on UNIX. The [...] In addition to this document, you will want to refer to a copy of the UNIX User Reference Manual. The csh USD:4-2 An Introduction to the C shell documentation in section 1 of the manual provides a full description of all features of the shell and is the [...] ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 ----- I would consider the repeated page headers (USD:4-2 An Introduction to the C shell) useless, we deliberately didn't implement these in mandoc(1). For ABSTRACT (and other headers), .Sh and .Ss could be used; losing the centering doesn't seem like a grave problem. So what remains is the title and author. The title could just be provided by Nd, and the author information moved to the end into the AUTHORS section, and no changes to the mdoc(7) language would be required at all. For example: ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 ----- ischwarze@isnote $ cat csh.mdoc .Dd $Mdocdate$ .Dt CSH-INTRO 1 .Os .Sh NAME .Nm CSH-INTRO .Nd An Introduction to the C shell .Sh ABSTRACT .Nm csh is a new command language interpreter for UNIX systems. It incorporates good features of other shells and a history mechanism similar to the .Sq redo of INTERLISP. [...] .Sh AUTHORS .An -nosplit .An William Joy (revised for 4.3BSD by .An Mark Seiden ) .br Computer Science Division, Department of Electrical Engineering and Computer Science, University of California, Berkeley .br Berkeley, California 94720 schwarze@isnote $ mandoc csh.mdoc CSH-INTRO(1) OpenBSD Reference Manual CSH-INTRO(1) NAME CSH-INTRO - An Introduction to the C shell ABSTRACT csh is a new command language interpreter for UNIX systems. It incorporates good features of other shells and a history mechanism similar to the `redo' of INTERLISP. [...] AUTHORS William Joy (revised for 4.3BSD by Mark Seiden) Computer Science Division, Department of Electrical Engineering and Computer Science, University of California, Berkeley Berkeley, California 94720 OpenBSD 5.5 June 14, 2014 OpenBSD 5.5 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 ----- So that adds the not strictly required header and footer lines, the word "NAME", and the identifier "CSH-INTRO". Do these do any harm? If you choose to install the document as a man page, they may even be useful. Regarding the AUTHORS, you might also move them to the top, right after NAME, if you are not using any of the standard sections like SYNOPSIS, DESCRIPTION, and so on. In case you don't consider this good enough, what exactly do you think is required, so which changes/options/features would you consider the minimum that would need to be changed in mandoc or added to mandoc? Please try to provide a list that is complete and as specific as possible, that will make it easier to judge the effort required (and maybe to provide an implementation that actually does what you want). Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv