Date: Wed, 25 Aug 1999 12:38:19 +0100 From: Nik Clayton <nik@freebsd.org> To: "Jordan K. Hubbard" <jkh@zippy.cdrom.com> Cc: Nik Clayton <nik@FreeBSD.ORG>, jack <jack@germanium.xtalwind.net>, current@FreeBSD.ORG, asami@freebsd.org, doc@freebsd.org Subject: Re: Docs blows up make release Message-ID: <19990825123819.A2177@kilt.nothing-going-on.org> In-Reply-To: <3164.935357152@localhost>; from Jordan K. Hubbard on Sun, Aug 22, 1999 at 02:25:52PM -0700 References: <19990822110511.A89933@kilt.nothing-going-on.org> <3164.935357152@localhost>
next in thread | previous in thread | raw e-mail | index | archive | help
--NzB8fVQJ5HfG6fxh
Content-Type: text/plain; charset=us-ascii
[ I've added Satoshi Asami to the cc: list -- I figure he's almost certainly
on -current, but I wanted to make sure he sees this and can add his input
as necessary.
I've also added -doc, for information. ]
On Sun, Aug 22, 1999 at 02:25:52PM -0700, Jordan K. Hubbard wrote:
> Nik Clayton wrote:
> > For the immediate future, it looks like it will -- it seems as though
> > we don't have the man power to make the necessary changes to sysinstall
> > to support "installing the docs as packages", so I'm going to fix up
> > src/release/Makefile as necessary to cope with the new directory structure.
Just an update on that. I've been working on this with Jack O'Neill, and
if the reports are favourable I'll have one small patch to
src/release/Makefile and one small patch to doc/*/Makefile to go in some
time in the next 48 hours or so which should get release builds working.
Note that this won't include any fixes to teach sysinstall about the new
paths under /usr/share/doc/, although you should have seen a patch I sent
you about that by now.
> I also should note that there's nothing to preclude supplying the docs
> as packages *also*, assuming that they appear in the INDEX and get
> built as part of Satoshi's ports build.
This assumes that the documentation is also listed in the ports tree.
I don't think this is a great idea -- more specifically, I don't think
this is a great idea as the primary mechanism for making packages of
the documentation. I've got no problems with it being another way to
make doc packages.
As the comment for ports/japanese/handbook says, "this is pretty useless
as a port, but is here so I can build a package -- Satoshi".
This makes the ports tree have a dependency on the doc tree. I don't think
this dependency should be there. It's bad enough that the src/ tree
depends on doc/ (and the reason I want the documentation available as
packages is to remove this dependency), having ports depend on the doc tree
as well just means that when things go out of sync in doc for a while I get
both you and Satoshi complaining at me, instead of just you :-)
Putting the package building rules in the doc/ Makefiles also (and this
is just my personal opinion) makes it easier for people to see how the
documentation packages are built. The ports Makefile structure is a
marvel, but it contains a lot of code that's not necessary for building
documentation packages (the "automagically add man pages to the PLIST
i" code, for example) that makes it more difficult for the interested
learner to browse and understand what's going on.
I've attached the patch to docproj.docbook.mk that tells it how to build
packages to this message. To use it.
1. Checkout a recent copy of the doc/ repository.
2. Patch doc/share/mk/docproj.docbook.mk with the attached patch.
3. Pick a directory, such as the English FAQ
# cd doc/en_US.ISO_8859-1/books/faq
4. Make sure that a COMMENT and DESCR file exist. I haven't committed
any of these yet, so the simplest thing to do is
# touch COMMENT DESCR
5. Run "make package", ensuring that the FORMATS variable is set to the
formats you want to build.
# make "FORMATS=html html-split ps pdf rtf" package
6. Sit back and relax, it takes a while. When it's finished, look at
the .tgz files that have been created. Note that package building
*will* update the installed documentation under /usr/share/doc/.
If there's a way to work around this (so that you can build the
package containing files in one directory, but so that when you run
pkg_add(1) the files are installed in a different directory) I'd like
to know about it.
This is still proof of concept. For example, when it's finished, it would
be nice if the DESCR could be automatically generated by pulling out the
<abstract>...</abstract> that might be in the source, and the name of the
generated package should probably be something like
<doc-name>.<lang-encoding>.<format>.tgz
so
faq.en_US.ISO_8859-1.pdf.tgz
But I think it currently fits the 80/20 rule reasonably well.
If you put COMMENT and DESCR files in all the appropriate directories you
should certainly be able to do something like
# cd /usr/doc
# make "FORMATS=html html-split ps pdf rtf" package
# find . -name \*.tgz -exec scp {} wcarchive:/archive/pub/FreeBSD/doc \;
which is how I intend to automate building these things and ensuring that
wcarchive is kept up to date.
Does that all make sense? I don't think there's anything there that's
egregiously stupid, but it's been known to happen before :-)
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>
--NzB8fVQJ5HfG6fxh
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/22 07:40:27
@@ -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-/}
# ------------------------------------------------------------------------
#
--NzB8fVQJ5HfG6fxh--
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?19990825123819.A2177>