From owner-freebsd-doc Wed Jul 7 3:40: 7 1999 Delivered-To: freebsd-doc@freebsd.org Received: from firewall2.lehman.com (firewall2.Lehman.COM [192.147.65.115]) by hub.freebsd.org (Postfix) with ESMTP id AB76114F62 for ; Wed, 7 Jul 1999 03:40:03 -0700 (PDT) (envelope-from nclayton@lehman.com) Received: from relay3.messaging-svcs5.lehman.com by firewall2.lehman.com (8.8.6/8.8.6) id GAA26389; Wed, 7 Jul 1999 06:39:55 -0400 (EDT) Message-ID: <19990707113922.V15628@lehman.com> Date: Wed, 7 Jul 1999 11:39:22 +0100 From: Nik Clayton To: Bob Van Valzah , nik@nothing-going-on.demon.co.uk Cc: doc@freebsd.org Subject: Re: FreeBSD Formatting Help References: <37820C68.3998AAA@WhiteBarn.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.93.2i In-Reply-To: <37820C68.3998AAA@WhiteBarn.com>; from Bob Van Valzah on Tue, Jul 06, 1999 at 09:02:17AM -0500 Organization: Lehman Brothers Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Bob, [ I've cc'd this reply to doc@FreeBSD.org, so that it gets in to the mail archives, and helps out any lurkers who might be wondering the same questions you are ] On Tue, Jul 06, 1999 at 09:02:17AM -0500, Bob Van Valzah wrote: > Nik, Many thanks for your FDP Tutorial material. I'm currently clawing > my way up the SGML learning curve on a FreeBSD system and your tutorial > has moved me along farthest with the least effort. It's good to know people are finding it useful. There are still gaps, but I'm working on closing them. > But I'm still a bit confused when it comes to actually formatting > DocBook docs with FreeBSD. Stream of consciousness questions: OK. > * Do I still need/want the sgmlfmt command from the sgmlformat-1.7 > package? Yes. The FAQ and a couple of the tutorials are still in LinuxDoc format, which needs sgmlformat. When they've converted to DocBook the need for sgmlformat disappears. > * What about the tex-3.14159 vs teTeX-0.9.981113 packages? You only need TeX if you want to produce Postscript or PDF output, otherwise it's not necessary. You should only have one of these installed. teTeX-beta is currently recommended, as it installs all the optional TeX packages (like hyperref) that are required by the Jade TeX macros. tex-3.14159 will probably work, but will need some configuring by hand. I'm not a hardcore TeX user, and can't advise on how you'd get tex-3.14159 to work for you. > * Do I need both? No. See above. Also, the teTeX port was recently upgraded to v1.05, which means it's now out of beta. You should actually be able to use the teTeX port now instead of the teTeX-beta port. > * Why is dvips available as a port and not as a package? Good question, don't know. The port maintainer is jmz@FreeBSD.org, who can probably explain why. > * Will I even need dvips? I don't think so. I haven't needed to install it by hand, so I assume a version of it comes with the teTeX port -- however, the version in the ports tree might be more up to date. In addition, if you're producing PDF output and not Postscript output then you don't need dvips. If you are producing PS output then you will need it (but as I say, I think it comes with teTeX). > * What does LaTeX have to do with any of this? It doesn't. As I understand it; TeX is the document formatting system. It's big, forbidding, and has lots of arcane commands to precisely control the layout of your document. You can also write macros in TeX. LaTeX is a commonly used macro package, that abstracts out a lot of the TeX syntax, so that you can write one command ("Make this document have 2 columsn from this point on") instead of the multitude of TeX commands you would otherwise need to write. The FDP doesn't use LaTeX at all -- the SGML sources are fed through a processor called Jade, which outputs TeX directly. The TeX output by Jade assumes that another TeX macro package is installed. This macro package is called JadeTeX. JadeTeX is like LaTeX in that it's purpose is to hide some of TeX's command structure and make it easier to use. The difference is that LaTeX is designed to be used by people, JadeTeX is designed to handle the output from Jade. > * How do I produce one giant .html file? Assuming you've got the doc's installed; % cd /path/to/doc/en/handbook % make FORMATS=html What's going on under the hood? The stylesheets we are using to convert from DocBook to HTML have a configurable parameter called "nochunks". If you tell the system to make the "html" format then it turns on this paramter by passing the "-V nochunks" option to Jade. This option is only understood by the stylesheets. Jade doesn't understand what "nochunks" means, it just passes it on to the stylesheets, which do understand what it means. > * How do I produce a linked tree of .html files? As above; % cd /path/to/doc/en/handbook % make FORMATS=html-split The default stylesheet behaviour is to produce split files. > * What does a Makefile look like that produces all these wonderful > formats from a single DocBook document? Take a look at /path/to/doc/en/handbook/Makefile which is the main Makefile for the Handbook. All this does is set a few variables. The body of the work is done in /path/to/doc/share/mk/docproj.docbook.mk If you know make(1) then this should be relatively easy to understand. It's heavily commented, because I expressly wanted other people to follow it relatively easily. The actual command lines that are run to convert the documentation to the various formats can be found by searching for ".MAIN" in this Makefile, and then looking at the targets below there. > > As you can probably tell, I'm coming at this from the point of view of a > FreeBSD use who just wants to be able to produce PDF/PostScript/HTML > from a single document base. Whatever the answers to these questions, I > think they'll make valuable additions to your tutorial and perhaps to > the DocBook FAQ as well. This is the more interesting comment. I'm a bit torn about how this should be done in FreeBSD. Through the ports system you can install all the applications you need. In particular, textproc/docproj brings in all the formatters, macro packages, and so on. What isn't in the system are any user friendly front-ends to make it easier for people such as yourself to actually use the tools. I *think* this is probably the right way to go. The FDP Makefiles (as explained above) are specifically for the FDP internal documentation (FAQ, Handbook, tutorials, and so on). They are not designed so that they can be taken out of the FDP and dropped in to someone elses documentation system, and just work. I think this is probably a good thing -- your documentation requirements are probably different from ours, which would mean that you would need to customise the Makefiles anyway -- it's better to provide you with clearly documented examples that you can cannabilise as necessary, than to try and write a collection of Makefiles that try and encompass everyone's requirements. That said, I could be wrong about this. The Linux Documentation Project came up with "sgmltools", which has since spun off to be a separate project (). However, it now seems to be spinning down, as the principle architect, Cees de Groot, has had to step back from it due to other commitments. In a nutshell, SGMLTools is/was a collection of Python scripts that did two things. 1. Managed the installation of the various programs necessary to convert DocBook to different formats. 2. Provided commands (like "db2html", "db2pdf", and so on) that just converted DocBook to one other format. All these commands do is call the underlying Jade, TeX, and other applications for you, trying to get the command line right. I don't think this is appropriate for FreeBSD for a few reasons. First, (1) above is already capably handled by the ports system. We don't need to reinvent that particular wheel. I'm unconvinced of the necessity of (2). In many cases the command line for converting from (say) DocBook to something like RTF is only one or two lines -- you can put this in a shell script yourself. And if you need anything more complex then you're almost certainly writing your own scripts and Makefile's anyway, so the additional layer of simplification doesn't really buy you anything anyway. Plus, of course, there's the fact that they're all written in Python. I've got nothing against Python as a language (I've never used it, but I've heard lots of good things about it[1]). But I'm not about to bring in something for the FDP that requires a whole new programming language to implement it. Oh, and the name "SGMLTools" is really a bit of a misnomer -- at version 1 the name would more properly have been "LinuxDoc Tools", and at the current version 2 it should be called "DocBook Tools". And FWIW, I've been active on the SGML Tools mailing list for the past year or so, and I have been keeping a close eye on what's been going on. But as I say, I'm not convinced it's the best solution for FreeBSD. For your particular situation, I'd recommend studying the doc/share/mk Makefile, and work out which bits you can lift from there to suit your purposes. You can then create your own documentation build environment, either using make(1), as we have, or with shell scripts, or whatever. I hope all that helps (you, and anyone else reading this). If you've got any more questions, don't hesitate to ask -- but if you can send 'em to doc@freebsd.org instead of direct to me, other people have a chance to get involved too. 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