Date: Fri, 29 Jun 2001 15:57:06 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: Building individual handbook chapters Message-ID: <20010629155706.C323@canyon.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
--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 <example>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 <part>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 -->
<!ENTITY rel.current CDATA "4.3">
+
+<!ENTITY % chap.introduction "IGNORE">
+<!ENTITY % chap.install "IGNORE">
+<!ENTITY % chap.basics "IGNORE">
+<!ENTITY % chap.ports "IGNORE">
+<!ENTITY % chap.boot "IGNORE">
+<!ENTITY % chap.users "IGNORE">
+<!ENTITY % chap.kernelconfig "IGNORE">
+<!ENTITY % chap.security "IGNORE">
+<!ENTITY % chap.printing "IGNORE">
+<!ENTITY % chap.disks "IGNORE">
+<!ENTITY % chap.backups "IGNORE">
+<!ENTITY % chap.x11 "IGNORE">
+<!ENTITY % chap.l10n "IGNORE">
+<!ENTITY % chap.sound "IGNORE">
+<!ENTITY % chap.serialcomms "IGNORE">
+<!ENTITY % chap.ppp-and-slip "IGNORE">
+<!ENTITY % chap.advanced-networking "IGNORE">
+<!ENTITY % chap.mail "IGNORE">
+<!ENTITY % chap.cutting-edge "IGNORE">
+<!ENTITY % chap.contrib "IGNORE">
+<!ENTITY % chap.policies "IGNORE">
+<!ENTITY % chap.kerneldebug "IGNORE">
+<!ENTITY % chap.linuxemu "IGNORE">
+<!ENTITY % chap.mirrors "IGNORE">
+<!ENTITY % chap.bibliography "IGNORE">
+<!ENTITY % chap.eresources "IGNORE">
+<!ENTITY % chap.staff "IGNORE">
+<!ENTITY % chap.pgpkeys "IGNORE">
+<!ENTITY % chap.hw "IGNORE">
+
]>
=20
<book>
@@ -74,55 +105,55 @@
<part>
<title>Getting Started</title>
=20
- &chap.introduction;
- &chap.install;
- &chap.basics;
- &chap.ports;
+ <![ %chap.introduction; [ &chap.introduction; ]]>
+ <![ %chap.install; [ &chap.install; ]]>
+ <![ %chap.basics; [ &chap.basics; ]]>
+ <![ %chap.ports; [ &chap.ports; ]]>
</part>
=20
<part>
<title>System Administration</title>
=20
- &chap.boot;
- &chap.users;
- &chap.kernelconfig;
- &chap.security;
- &chap.printing;
- &chap.disks;
- &chap.backups;
- &chap.x11;
- &chap.l10n;
- &chap.sound;
+ <![ %chap.boot; [ &chap.boot; ]]>
+ <![ %chap.users; [ &chap.users; ]]>
+ <![ %chap.kernelconfig; [ &chap.kernelconfig; ]]>
+ <![ %chap.security; [ &chap.security; ]]>
+ <![ %chap.printing; [ &chap.printing; ]]>
+ <![ %chap.disks; [ &chap.disks; ]]>
+ <![ %chap.backups; [ &chap.backups; ]]>
+ <![ %chap.x11; [ &chap.x11; ]]>
+ <![ %chap.l10n; [ &chap.l10n; ]]>
+ <![ %chap.sound; [ &chap.sound; ]]>
</part>
=20
<part>
<title>Network Communications</title>
=20
- &chap.serialcomms;
- &chap.ppp-and-slip;
- &chap.advanced-networking;
- &chap.mail;
+ <![ %chap.serialcomms; [ &chap.serialcomms; ]]>
+ <![ %chap.ppp-and-slip; [ &chap.ppp-and-slip; ]]>
+ <![ %chap.advanced-networking; [ &chap.advanced-networking; ]]>
+ <![ %chap.mail; [ &chap.mail; ]]>
</part>
=20
<part>
<title>Advanced topics</title>
=20
- &chap.cutting-edge;
- &chap.contrib;
- &chap.policies;
- &chap.kerneldebug;
- &chap.linuxemu;
+ <![ %chap.cutting-edge; [ &chap.cutting-edge; ]]>
+ <![ %chap.contrib; [ &chap.contrib; ]]>
+ <![ %chap.policies; [ &chap.policies; ]]>
+ <![ %chap.kerneldebug; [ &chap.kerneldebug; ]]>
+ <![ %chap.linuxemu; [ &chap.linuxemu; ]]>
</part>
=20
<part>
<title>Appendices</title>
=20
- &chap.mirrors;
- &chap.bibliography;
- &chap.eresources;
- &chap.staff;
- &chap.pgpkeys;
- &chap.hw;
+ <![ %chap.mirrors; [ &chap.mirrors; ]]>
+ <![ %chap.bibliography; [ &chap.bibliography; ]]>
+ <![ %chap.eresources; [ &chap.eresources; ]]>
+ <![ %chap.staff; [ &chap.staff; ]]>
+ <![ %chap.pgpkeys; [ &chap.pgpkeys; ]]>
+ <![ %chap.hw; [ &chap.hw; ]]>
</part>
</book>
=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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010629155706.C323>