From owner-freebsd-doc Fri Jun 29 7:56:57 2001 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (tserver.conference.usenix.org [199.103.159.3]) by hub.freebsd.org (Postfix) with ESMTP id 66FE537B40A for ; Fri, 29 Jun 2001 07:56:38 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.11.3/8.11.3) id f5TEv6F00691 for doc@freebsd.org; Fri, 29 Jun 2001 15:57:06 +0100 (BST) (envelope-from nik) Date: Fri, 29 Jun 2001 15:57:06 +0100 From: Nik Clayton To: doc@freebsd.org Subject: Building individual handbook chapters Message-ID: <20010629155706.C323@canyon.nothing-going-on.org> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-md5; protocol="application/pgp-signature"; boundary="oj4kGyHlBMXGt3Le" Content-Disposition: inline User-Agent: Mutt/1.2.5i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org --oj4kGyHlBMXGt3Le Content-Type: multipart/mixed; boundary="pAwQNkOnpTn9IO2O" Content-Disposition: inline --pAwQNkOnpTn9IO2O Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable I had a moment of clarity yesterday when talking to Murray Stokely. Attached are some patches that let you build individual handbook chapters, for testing, without needing to build the whole handbook (which can take a lot of time). There are basically two approaches to doing this. 1. Since the individual chapter.sgml files are not, by themselves, valid SGML (because they have no DOCTYPE line), you can't process them with jade directly. Instead, you would need to do something like: 1. Store the DOCTYPE line in a separate file. 2. cat(1) this file, and chapter.sgml together, then pipe the result through jade. The problem with this approach is that you see the chapter completely stand alone -- this is fine for most things, but if=20 you are testing out index entries that you've added, or want to make sure that s appear properly in the list of examples then you need to build the whole book. So, approach #2. . . 2. Make each chapter's appearance conditional on a parameter entity. Have these entities default to "IGNORE". For the full handbook build set these all the "INCLUDE" with the "-i" flag to Jade. For individual chapter builds, turn on just the entity for that chapter. This then lets you build a version of the Handbook without certain chapters (or, more germane to this discussion, with all chapters but one turned off). The patches are: book.sgml.diff Add parameter entities for each chapter, and wrap each chapter's in them, for conditional inclusion. Makefile.diff Introduce a new variable, CHAPTERS, which lists the names of the chapters to build. Fiddle with the JADEFLAGS variable to make sure that each chapter in CHAPTERS has a corresponding '-i ...' flag when passed to Jade. These two diffs keep things the same for the standard Handbook build. ports.Makefile A Makefile to go in a chapter subdirectory, in this case ports/Makefile. This should be self explanatory. If you do this you can then do cd ....../handbook/ports make index.html and it will generate a copy of the Handbook with just this chapter in the current directory. There will be some errors -- cross references to other chapters won't work, and you will then have several s in the Handbook with no content, which is invalid SGML. However, these errors won't cause the build to fail, and since this is to make it easier for authors to test things while they make changes, it's really not important. The only thing that doesn't work with this scheme is images. If you do try and build a chapter with images in they won't appear, because of the relative path scheme we use. An alternative approach (say, for the advanced-networking chapter) would be to do cd ......./handbook make CHAPTERS=3Dadvanced-networking/chapter.sgml index.html which should do the right thing. I'll probably commit these in 24 hours or so. N --=20 FreeBSD: The Power to Serve http://www.freebsd.org/ FreeBSD Documentation Project http://www.freebsd.org/docproj/ --- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 --- --pAwQNkOnpTn9IO2O Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="Makefile.diff" Content-Transfer-Encoding: quoted-printable Index: Makefile =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/Makefile,v retrieving revision 1.34 diff -u -r1.34 Makefile --- Makefile 2001/06/23 22:46:14 1.34 +++ Makefile 2001/06/29 01:11:41 @@ -13,7 +13,7 @@ INSTALL_COMPRESSED?=3D gz INSTALL_ONLY_COMPRESSED?=3D =20 -# IMAGES=3D advanced-networking/natd.png advanced-networking/natd.eps +#IMAGES=3D advanced-networking/natd.eps =20 #=20 # SRCS lists the individual SGML files that make up the document. Changes @@ -58,6 +58,11 @@ SRCS+=3D chapters.ent=20 =20 SYMLINKS=3D ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?=3D ${SRCS:M*chapter.sgml} + +JADEFLAGS+=3D ${CHAPTERS:S/\/chapter.sgml//:S/^/-i chap./} =20 # XXX The Handbook build currently overflows some internal, hardcoded=20 # limits in pdftex. Until we split the Handbook up, build the PDF=20 --pAwQNkOnpTn9IO2O Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="book.sgml.diff" Content-Transfer-Encoding: quoted-printable Index: book.sgml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/book.sgml,v retrieving revision 1.101 diff -u -r1.101 book.sgml --- book.sgml 2001/06/21 03:38:14 1.101 +++ book.sgml 2001/06/29 04:24:10 @@ -25,6 +25,37 @@ create some links on web sites and such, so do NOT change it until it's really release time --> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]> =20 @@ -74,55 +105,55 @@ Getting Started =20 - &chap.introduction; - &chap.install; - &chap.basics; - &chap.ports; + + + + =20 System Administration =20 - &chap.boot; - &chap.users; - &chap.kernelconfig; - &chap.security; - &chap.printing; - &chap.disks; - &chap.backups; - &chap.x11; - &chap.l10n; - &chap.sound; + + + + + + + + + + =20 Network Communications =20 - &chap.serialcomms; - &chap.ppp-and-slip; - &chap.advanced-networking; - &chap.mail; + + + + =20 Advanced topics =20 - &chap.cutting-edge; - &chap.contrib; - &chap.policies; - &chap.kerneldebug; - &chap.linuxemu; + + + + + =20 Appendices =20 - &chap.mirrors; - &chap.bibliography; - &chap.eresources; - &chap.staff; - &chap.pgpkeys; - &chap.hw; + + + + + + =20 --pAwQNkOnpTn9IO2O Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename=Makefile # # Build the Handbook with just the content from this chapter. # # $FreeBSD$ # CHAPTERS= ports/chapter.sgml VPATH= .. MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} DOC_PREFIX?= ${.CURDIR}/../../../.. .include "../Makefile" --pAwQNkOnpTn9IO2O-- --oj4kGyHlBMXGt3Le Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjs8l0EACgkQk6gHZCw343W+xQCfaSF9jB1dfJoA+j349Niv8ctv eWYAn3S7Q6VUvGoNnC09jcwLu5fTvPKG =iQ81 -----END PGP SIGNATURE----- --oj4kGyHlBMXGt3Le-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message