Date: Sat, 21 Aug 1999 16:26:05 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: Turning formatted docs in to packages Message-ID: <19990821162604.A65171@catkin.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
--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-<format>
(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}.<format>.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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990821162604.A65171>