From owner-freebsd-doc Fri Jan 15 02:26:33 1999 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id CAA20822 for freebsd-doc-outgoing; Fri, 15 Jan 1999 02:26:33 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from firewall1.lehman.com (firewall1.Lehman.COM [192.147.65.82]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id CAA20817; Fri, 15 Jan 1999 02:26:31 -0800 (PST) (envelope-from nclayton@lehman.com) From: nclayton@lehman.com Received: from relay.lehman.com by firewall1.lehman.com (8.8.6/8.8.6) id FAA16960; Fri, 15 Jan 1999 05:25:13 -0500 (EST) Received: from cmgrelay1.messaging-svcs.lehman.com by relay.lehman.com (4.1/LB-0.6) id AA20035; Fri, 15 Jan 99 05:24:41 EST Received: from lonmailhost.lehman.com by cmgrelay1.messaging-svcs.lehman.com (8.8.5/8.8.5) id FAA29906; Fri, 15 Jan 1999 05:24:40 -0500 (EST) Received: from lonadminvnm.lehman.com by lonmailhost.lehman.com (SMI-8.6/Lehman Bros. V1.5) id KAA08183; Fri, 15 Jan 1999 10:24:39 GMT Received: from lonadmin80.lehman.com by lonadminvnm.lehman.com (4.1/Lehman Bros. V1.6) id AA13571; Fri, 15 Jan 99 10:24:38 GMT Received: by lonadmin80.lehman.com (SMI-8.6/Lehman Bros. V1.5) id KAA22114; Fri, 15 Jan 1999 10:24:38 GMT Message-Id: <19990115102437.R18103@lehman.com> Date: Fri, 15 Jan 1999 10:24:37 +0000 To: Jay Nelson , nik@FreeBSD.ORG Cc: doc@FreeBSD.ORG Subject: Re: TeX problems; Doc. Proj. needs you! References: <19981107211208.12650@nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.91.1i In-Reply-To: ; from Jay Nelson on Mon, Jan 11, 1999 at 09:47:00PM -0600 Organization: Lehman Brothers Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Hi Jay, Sorry for the delay, I've been slightly swamped this week. I've cc'd this to the -doc mailing list, so that other interested parties can chime in as necessary. On Mon, Jan 11, 1999 at 09:47:00PM -0600, Jay Nelson wrote: > I've recently found myself in a position where I needed to learn more > about SGML and remembered this email, so I thought maybe I could learn > and do some good at the same time. I'm only concerned with book > production output, so I've only looked at the TeX portion so far. OK. Sounds good. > That's raised a number of questions and some observations. Take the > observations with a grain of salt, since I'm still not sure what I > don't know about SGML and DSSSL. > > Should we be doing this in TeX or troff? (TeX would be my prefered > weapon of choice -- but past books, I believe have been done in > troff.) At the moment, we can only do this in TeX. You probably already know this, but this in case. . . This is because of Jade. Specifically, Jade reads in the document and the stylesheet. It then produces a formatted version of the document (where the formatting instructions are internal to Jade). It hands this formatted version off to whichever Jade backend has been selected, and it is the responsibility of the backend to convert the Jade formatting instructions into the instructions used by the backend. Jade has a number of backends. RTF is built in to it. The TeX backend doesn't write raw TeX. Instead it writes TeX that makes lots of macro calls that roughly correspond with the internal Jade format. The TeX that is written by Jade needs to be processed with a collection of macros that actually implement the code that Jade calls. Hence the need for JadeTeX by Sebastien Rahz. If we were to do this in *roff Jade would need a *roff backend. I believe Chuck Robey has been looking at this, but the last I spoke to him (about a week ago) he was still working his way through the Jade source code, and didn't have anything that could be tested. If you're interested in working with him on implementing this then let me know. Currently, we have a small problem with the JadeTeX macros -- they don't handle some of the constructions in the Handbook. Sebastien has sent me a new version, which fixes this problem but breaks PDF output. He knows about this bug, and is working on a fix. If you've got the TeX skills to work on this as well, please let me know. > What are the TeX goals? Is this something that Walnut Creek is likely > to publish and should I use Greg's book as a style guide? > Specifically, should I convert the Garamond fonts used in "The > Complete FreeBSD" for use with TeX and possibly troff and stay with > the modified quarto format? I don't know if WC is likely to publish it, because they already publish Greg's book. I think it's more important that it be easy for the user to download and print -- this means at least two versions of each format produced (one at US Letter size, one at A4 size), and available in as many useful formats as possible (particularly for Windows and Mac users). I'm pretty certain we've got this covered, with the PDF generation (when it works). > The generation of one huge TeX file is rather dissatisfying Not sure I understand this bit. > and not very practical from a production standpoint. Not sure. Going from .sgml to .tex to .dvi to .ps takes about 10 minutes on my 64MB P200, however. . . > Any problems with breaking it down on a chapter basis? Would this break > the HTML generation? It's already broken down into chapters (look in doc/en/handbook), it just needs a framework so that Jade will process individual chapters. Note that this breaks when you try and refer to sections in another chapter. However, I have another, preferred approach to this -- in the long run I want to break the Handbook out in to a number of separate books, a little like the Linux HOWTOs (but with more control over their structure). You'd have handbooks (note: little 'h', not big 'H') of between 30 and 100 pages (or so) with titles like Read this first Configuring FreeBSD Installing Applications Monitoring and limiting users Printing and so on. The idea is that each one is entirely self-contained and repeats as little information as possible from any other book(let). While this is not vastly different from what we have at the moment (the new books would be organised along roughly the same lines as the existing chapters) because they are books they are more self contained, and it makes it easier to produce them individually (and therefore download them individually). These would then comprise the _FreeBSD Documentation Set_. I've written up a lot more about this which appeared in a thread on the -doc mailing list. Take a look at http://www.freebsd.org/~nik/hb/comments.txt and http://www.freebsd.org/~nik/hb/new-layout.txt and http://www.freebsd.org/~nik/hb/old-layout.txt This is quite a radical change, and the first thing I intend to tackle when the Jade issues have been worked out. > The raw jade output is horrible, and generally, bad bookwork. Pass. I'm not sufficiently up on TeX to comment. > Inclusion of an additional style sheet is required to make a decent > book. I'm not sure where that is best done. So far, I've added the > redefinitions to freebsd.dsl under the %output.print section, but > that's not the best place to put specific, local definitions. What do > you suggest? What is the best way to include local style > modifications? If you wanted to override the definitions in freebsd.dsl then create your own file (local.dsl?) and include freebsd.dsl in the same way that freebsd.dsl includes Norm's stylesheets. > I've noticed some failures of either the SGML or the TeX translation > and, except for some missing end tags, I suspect it's in the TeX > translation. Should I be looking at the SGML or the instant > translation files? If the translation files, how do you want any > changes to them managed? 'instant'? The new Handbook won't be going anywhere near 'instant' and the transpecs. It's DSSSL all the way. > I'm not too happy with the LaTeX orientation of the jadetex macros, > but then I've never liked LateX because it never offered what I > needed. Do you have a preference between keeping the jadetex macros > and rewriting the macro package? A rewrite would make the stylesheet > issue simpler, but would not simplify variations. "As long as it works" :-) You're probably better off talking to Sebastien Rahz () and James Clark () directly I think. > The jpja language business is broken in the modular docbook package, > and, at this point, I haven't figured out how to fix it or make the > error messages go away. I fact, I doubt I could make it work properly. > Is anyone working on this? Jun Kuriyama who wrote them I believe. I think the jpja stuff will be rolled in to a future release of Norm's stylesheets, so this issue should sort itself out. N -- --+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+-- --+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message