From owner-freebsd-doc Fri Sep 3 10: 8:19 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 20FF914DC0 for ; Fri, 3 Sep 1999 10:07:10 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18]) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id RAA87798; Fri, 3 Sep 1999 17:47:30 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by kilt.nothing-going-on.org (8.9.3/8.9.3) id PAA06502; Fri, 3 Sep 1999 15:17:35 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Date: Fri, 3 Sep 1999 15:17:35 +0100 From: Nik Clayton To: Eric Brunner Cc: doc@FreeBSD.ORG Subject: Re: Query -- editor(s) Message-ID: <19990903151735.G99849@kilt.nothing-going-on.org> References: <199909022351.TAA26000@world.std.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <199909022351.TAA26000@world.std.com>; from Eric Brunner on Thu, Sep 02, 1999 at 07:51:22PM -0400 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Thu, Sep 02, 1999 at 07:51:22PM -0400, Eric Brunner wrote: > What are my choices for writing, assuming that for some reason(s) > I want some degree of consistency between what I am writing and > the handbook? For the moment, assume that I'm writing a section, > knowing my material, but using vi and no tool (or method) more > sophisticated than occasionally browsing a page-in-progress. I'm > more than a little concerned that producing subsequent work for > publication (in roff, TeX, or Postscript) from my common text will > require more work later... I *think* this is two questions -- the first is which DTD, the second is which editor makes using that DTD simple. The DTD choice is easy -- DocBook, or the FreeBSD extended version of it (which only adds a few new elements, which you may not need. The editor choice is more personal. I use Xemacs, because the SGML editing support is pretty good, and it's got nice pull down menus so I don't go mad trying to learn all the M-x combinations (selecting "Regexp replace" from a menu is better for me than trying to remember whether it's "M-x replace-regexp" or "M-x regexp-replace", or whatever the actual function is called). Other's mileage may vary. That lets you write the 'source' to your document. For easy viewing, you probably then want to be able to 'compile' it to HTML, or Postscript. For that you can use the tools in the textproc/docproj port (Jade and TeX, specifically). This will give you the same 'look and feel' as the FDP documents that are currently available. Those are quite 'big' tools though, and can take some time to process large documents. You may find it easier to use a tool like sgmlfmt (also in the docproj port) which is smaller and faster -- your HTML output won't look the same, which is probably not a problem, and you can still preview your work. > So, if I were the happy volunteer who drew the short straw for > the jrandom section of the handbook, posessed only of 2.2.8, what > would be my production tool kit? My personal approach would be to try and install the docproj port, and see how much of that works on 2.2.8. Jade *should*, but it's been a long time since I tried it. If it does work, then great, because you can lever the FDP make infrastructure to make using the tools a no-brainer. You can download the doc/share/* and doc/en_US.ISO_8859-1/* directories from CVS, and then add your document under the hierarchy, copy and tweak one of the existing Makefiles, and away you go. If Jade doesn't work then you can fall back to using sgmlfmt and related apps. These aren't used by the FDP anymore, but you can see examples of their use in the /usr/share/mk/bsd.sgml.mk file. Use whichever editor you're comfortable with. If it's got hooks for processing SGML documents then so much the better. N -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message