From owner-freebsd-doc Sat Aug 21 9:37:19 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 3AA0C14F64 for ; Sat, 21 Aug 1999 09:35:50 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id QAA67035 for doc@freebsd.org; Sat, 21 Aug 1999 16:26:05 +0100 (BST) (envelope-from nik) Date: Sat, 21 Aug 1999 16:26:05 +0100 From: Nik Clayton To: doc@freebsd.org Subject: Turning formatted docs in to packages Message-ID: <19990821162604.A65171@catkin.nothing-going-on.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary=nFreZHaLTZJo0R7j X-Mailer: Mutt 0.95.4i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --nFreZHaLTZJo0R7j Content-Type: text/plain; charset=us-ascii -doc, As has been mentioned before, one of the aims behind the recent repo move was to clear up the whole doc/ building framework so that it was considerably easier to add new functionality. One of the new pieces of functionality that people have been asking for is to have the formatted documentation (PS, PDF, RTF, HTML, and so on) be available for easy download -- not everyone wants to download Jade, and TeX before they can see the FAQ in PDF format, for example. To fit this in with FreeBSD, the simplest approach would seem to be to create a collection of packages (i.e., something that you can run pkg_add(1) on), so that the end-user can do something like pkg_add ftp://ftp.freebsd.org/pub/docs/pkg/faq-en_US.ISO_8859-1-html.tgz or pkg_add ftp://ftp.freebsd.org/pub/docs/pkg/handbook-zh_TW.Big5-pdf.tgz or whatever. This makes it much easier for the end user to keep their installed documentation up to date, and to use commands like pkg_info(1) to see which documentation they have got installed. This also makes building releases easier -- currently, building the documentation is part of the action carried out by "make release". This increases the amount of time it takes to build a release, makes the whole "building a release" process more fragile, and puts an extra burden on us to ensure that any changes we make to the doc/ build process don't break "make release". To this end, attached, find a patch to docproj.docbook.mk, that implements a package building target. You can use this in one of two ways; % make package This will build packages of all documentation, based on the current value of the FORMATS variable. % make package- (i.e., "make package-pdf" or "make package-html") This will build a package of the current documentation in just that format. The packages are called {book,article}..tgz, and are placed in the current directory. I'd appreciate interested parties taking a look at this on their systems, and making any comments as necessary. One thing -- I believe the FreeBSD packages require that each package has a one line comment, and a (possibly) multi-line description. If you test this, you will need to add these to each piece of documentation you test it with. For example; [ after patching docproj.docbook.mk appropriately ] # cd doc/en_US.ISO_8859-1/books/faq # echo "English (US ISO-8859-1 encoding) version of the FreeBSD FAQ" \ > COMMENT # cp COMMENT DESCR # make package Note also that as part of the package building process, the documentation *will* be installed in to ${DOCDIR} (probably /usr/doc on your system). Once you've created the packages, please try adding and deleting them from your system, and check that it all works OK for you. N -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> --nFreZHaLTZJo0R7j Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename=patch Index: docproj.docbook.mk =================================================================== RCS file: /home/ncvs/doc/share/mk/docproj.docbook.mk,v retrieving revision 1.9 diff -u -r1.9 docproj.docbook.mk --- docproj.docbook.mk 1999/08/19 00:07:09 1.9 +++ docproj.docbook.mk 1999/08/21 15:10:16 @@ -90,7 +90,7 @@ JADEOPTS= ${JADEFLAGS} -c ${FREEBSDCATALOG} -c ${DSSSLCATALOG} -c ${DOCBOOKCATALOG} -c ${JADECATALOG} ${EXTRA_CATALOGS:S/^/-c /g} -KNOWN_FORMATS= html html-split html-split.tar txt rtf ps pdf tex dvi tar doc +KNOWN_FORMATS= html html-split html-split.tar txt rtf ps pdf tex dvi tar # ------------------------------------------------------------------------ # If DOC_PREFIX is not set then try and generate a sensible value for it. @@ -279,6 +279,36 @@ validate: nsgmls -s -c ${FREEBSDCATALOG} -c ${DOCBOOKCATALOG} ${EXTRA_CATALOGS:S/^/-c /g} ${DOC}.sgml + +# ------------------------------------------------------------------------ +# +# Package building +# + +# +# Build a list of package targets for each output format. Each package +# target depends on the corresponding install target running. +# +.for _curformat in ${KNOWN_FORMATS} +_cf=${_curformat} +package-${_curformat}: install-${_curformat} + rm PLIST +.if ${_cf} == "html-split" + cp HTML.manifest PLIST +.else + echo ${DOC}.${_curformat} > PLIST +.endif + pkg_create -v -c COMMENT -d DESCR -f PLIST -p ${DESTDIR} \ + ${DOC}.${_curformat}.tgz +.endfor + +# +# Build one or more pkg_add(1)'able packages, based on all the current +# values of ${FORMATS}. Do this by listing all the appropriate +# package-* targets as dependencies. +# + +package: ${FORMATS:S/^/package-/} # ------------------------------------------------------------------------ # --nFreZHaLTZJo0R7j-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message