From owner-freebsd-doc Mon Mar 29 23:12:11 1999 Delivered-To: freebsd-doc@freebsd.org Received: from firewall2.lehman.com (firewall.Lehman.COM [192.147.65.67]) by hub.freebsd.org (Postfix) with ESMTP id 1B21114D16 for ; Mon, 29 Mar 1999 23:12:09 -0800 (PST) (envelope-from nclayton@lehman.com) Received: from relay.messaging-svcs2.lehman.com by firewall2.lehman.com (8.8.6/8.8.6) id CAA08881; Tue, 30 Mar 1999 02:11:48 -0500 (EST) Received: from lonmailhost.lehman.com by relay.messaging-svcs2.lehman.com (8.9.3/8.8.5) id CAA23481; Tue, 30 Mar 1999 02:11:16 -0500 (EST) Received: by lonmailhost.lehman.com (SMI-8.6/Lehman Bros. V1.5) id IAA14841; Tue, 30 Mar 1999 08:11:15 +0100 Message-ID: <19990330081115.S14492@lehman.com> Date: Tue, 30 Mar 1999 08:11:15 +0100 From: nclayton@lehman.com To: Joel Ray Holveck Cc: Kris Kennaway , Nik Clayton , doc@FreeBSD.ORG Subject: Re: Handbook DocBook cutover complete References: <19990327162554.K3136@catkin.nothing-going-on.org> <19990329105741.L23968@lehman.com> <86r9q7egfq.fsf@detlev.UUCP> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.91.1i In-Reply-To: <86r9q7egfq.fsf@detlev.UUCP>; from Joel Ray Holveck on Mon, Mar 29, 1999 at 10:42:49PM -0600 Organization: Lehman Brothers Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Mon, Mar 29, 1999 at 10:42:49PM -0600, Joel Ray Holveck wrote: > >> Can I ask what the differences and benefits are? > > As follows; > > * LinuxDoc is descended from the QWERTZ DTD, and was designed to serve > > the needs of the Linux Documentation Project. > > How do these needs differ from those of the FreeBSD documentation > project? They're not radically different. The LDP had a lot of people used to LaTeX, and wanted something that would map to that quite easily, which LinuxDoc does. DocBook existed then, but they didn't choose it for some reason. Whether this was because of "not invented here" syndrome, or something else, I don't know. > > When processed, both those might be displayed in a monospaced font. > > However, the DocBook version includes extra information. We don't do > > it yet, but the DocBook Handbook will eventually include several > > indices. One of these will be a list of each page where each filename > > is mentioned, allowing you to quickly see all the places where (for > > example) ppp.conf is referred to. > > It also means that if, later on, we decide that filenames look cleaner > in italics instead of monospace (for instance), we can do so. Yep. We can even do so on a 'per output format' basis. From reading examples of other typeset documentation, I think filenames in italics for the print version would work well. For HTML (due to the poor rendering of italics on many screens) mono-spaced would be better. > > * DocBook is extensible. It's relatively easy to add your own elements, > > for things that are missing from DocBook. I've done this for the > > Handbook, adding things like "" and "". This is > > harder to with LinuxDoc. > > What are you using these tags for? freefall is a hostname. 127.0.0.1 is an IP address. ftp.freebsd.org is a fully qualified domain name. xx:xx:xx:xx:xx:xx is a MAC address. all and install are targets in a Makefile. DESTDIR is a variable that controls where files will be installed. See doc/share/sgml/freebsd.dtd for more information. > > * Tools to convert DocBook to other formats are not quite as advanced > > as the LinuxDoc tools, but are getting their rapidly. > > I would be interested in hearing your comments on DocBook tools, what > you find indispensable (both in the drafing process and for finals), > etc. [x]emacs for all editing, in conjunction with PSGML mode. It makes writing SGML much easier. Because DocBook contains no presentational markup you don't need a graphical editor (or at least, I don't). For proof-reading I tend to convert to Postscript, print it out, and annotate it. That's mostly because most of my proof reading time is spent on trains without a laptop, so this is the best approach for me. Turning DocBook in to HTML, Postscript, and other formats is relatively simple using Jade and some DSSSL stylesheets (all in the ports collection). At the moment, doc/en/handbook/Makefile contains all the logic to do this automatically. I'll be splitting this up in to an independent Makefile (bsd.docbook.mk?) soon, so that converting your own documents will be as simple as # # Makefile to convert foo.sgml to HTML, PS, etc # SRCS= foo.sgml FORMATS= html html-split ps rtf .include "bsd.docbook.mk" At some point I'll port (unless someone beats me to it) the SGML Tools package as well (which is just a set of wrappers around programs like Jade) so you can do docb2html foo.sgml That's not very high on my list of priorities though. > > As it currently stands in the repository, the DocBook Handbook can be > > converted to HTML, Postscript, plain text, and Microsoft RTF. A bug > > that I'll fix this week is currently preventing PDF generation. > > The GNU project is writing a converter to TeXinfo. That'll be handy. Have you got any pointers to more information? I couldn't see anything about this on www.gnu.org. Cheers, N -- --+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+-- --+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+-- --+==[ Year 2000 Testing: It's about time. . . ]==+-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message