Date: Tue, 27 May 2003 17:36:51 +0200 From: "Simon L. Nielsen" <simon@nitro.dk> To: freebsd-doc@freebsd.org Subject: Re: New build system Message-ID: <20030527153651.GM411@nitro.dk> In-Reply-To: <20030527153439.GL411@nitro.dk> References: <20030527153439.GL411@nitro.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
--rWhLK7VZz0iBluhq Content-Type: multipart/mixed; boundary="HeFlAV5LIbMFYYuh" Content-Disposition: inline --HeFlAV5LIbMFYYuh Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On 2003.05.27 17:34:39 +0200, Simon L. Nielsen wrote: > To get an idea of what to implement/support and to actually have > documentation for the build system, when completed, I have started a > article about it. It can be found in text version attached or at > http://simon.nitro.dk/freebsd/doc-buildsystem/article.html in HTML. And of course I forgot to attach it :-) Should be here this time. --=20 Simon L. Nielsen --HeFlAV5LIbMFYYuh Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="doc-buildsystem.txt" Content-Transfer-Encoding: quoted-printable Next generation FreeBSD documentation build system Simon L. Nielsen simon@nitro.dk =20 $FreeBSD: doc/en_US.ISO8859-1/articles/doc-buildsystem/article.sgml,v 1.1.1000.9 2003/05/27 14:57:09 simonln Exp $ Copyright (c) 2003 by The FreeBSD Documentation Project Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaim= er as the first lines of this file unmodified. 2. Redistributions in compiled form (transformed to other DTDs, convert= ed to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaim= er in the documentation and/or other materials provided with the distribution. Important: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMIT= ED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This document describes the authors proposal for FreeBSD Next Generation documentation build system. ---------------------------------------------------------------------- ---------------------------------------------------------------------- 1 Introduction This document tries to describe a new build system for the FreeBSD documentation, i.e. the doc/ part of the FreeBSD CVS repository. Next Generation is a bit overused, but the best I can come up with at th= is time. Please feel free to suggest alternatives. The updated working copy of this document is available at http://simon.nitro.dk/freebsd/doc-buildsystem/article.html. Please note that this document is in no way an official FreeBSD document (yet anyway), and are solely based on the authors ideas on how a new documentation build system could be. Warning: This document is still work in progress! Do not consider this document complete at all. Please send comments to <simon@nitro.dk> or FreeBSD documentation project mailing list. ---------------------------------------------------------------------- 2 Goals / requirements The categorization is mainly of the order of which things will be implemented/supported. All things in the must and should support lists will most likely get implemented. Note: When referring to building with OBJDIR what is actually meant is building the documentation where the temporary files are stored in /usr/obj instead of the source tree, by running make obj before building. Note: The ordering withing each list is more or less random. The new doc build system must support * Building then entire current documentation set. * Output in HTML (single and split), TXT, PDF, PS, and RTF formats. * Build both with and without OBJDIR. * Only build the images which are shared between translations once when building all translations. * Don't copy images when building (OBJDIR mainly). * The cleandir target should work with or without OBJDIR. * Support for DSSSL and XSL style sheets. * Good documentation of the build system including comments in the makefiles. * Support proper use of DESTDIR which does not conflict with the meani= ng in the normal FreeBSD source tree. * Consistent use of boolean variables. * Support for multiple HTML to text converters and a simple way to switch between them. Inspired by multiple threads about which ``converter'' to use on the FreeBSD documentation project mailing li= st and e.g. PR docs/50211. * Support compressing output with bzip2(1), gzip(1), compress(1) and zip. The new doc build system should support * XML DocBook documents. * XML DocBook build tools by converting SGML DocBook documents to XML DocBook documents during build. * Building on other operation systems than FreeBSD. * Use as much of the normal FreeBSD build system as possible; that is src/share/mk. * Output in PDB (Palm Pilot Documentation). * A simple way to ad pre/post process targets to each build stage. PR docs/33589. * Make folded books using psutils. PR docs/36432 * A simple documented way to negate all boolean variables. * Being style.Makefile(5) compatible. * Parallel builds using make -j X The new doc build system might support * HTML based documents (DOCFORMAT=3Dhtml). Note: Only en_US.ISO8859-1/articles/console-server uses the HTML input format. It might be simpler to convert the article in questi= on to SGML DocBook, rather than supporting HTML articles. * Support for path's with spaces. PR docs/35678. Note: It is unlikely that this is possible to support with the way make(1) works. ---------------------------------------------------------------------- 3 Implementation notes/thoughts To implement the actual installation of files bsd.files.mk can be used to allow a more flexible handling. Some parts of the installation might sti= ll need custom handling, since when using some output formats, e.g. the html-split, it is not know before the build, which files are produced, a= nd therefor needs to be installed. The language independent images can be handled by having them be created by a separate makefile in doc/share/images/ and then installing symbolic links in the build directory to the shared images. The shared images are then build under doc/share/images/ by another make process by using SUBD= IR or similar functionality. Note: It must be tested if all the build tools can actually handle symbolic links... Since shared images are now build in a sub make process dependencies does not work. To know which image types to generate for each format there mu= st be a mapping ``table'' instead of the old dependencies. The build/install can happen in several stages: Build stages 1. Build document images. a. Build general shared images. b. Symlink general shared images. c. Build per document shared images. d. Symlink per document shared images. e. Build per document per language specific images. 2. E.g. convert SGML to XML. 3. Build document (to HTML, TEX, PS and so on). 4. Install document and images. 5. Package document and images (e.g. tar(1) or zip). ---------------------------------------------------------------------- 3.1 TODO * Implement build of images. * Implement build of shared images. * Implement use of shared images in documents. * Implement build of SGML DocBook with HTML output. * Implement build of SGML DocBook with TEX/PS output. * Make build system work with stub bsd.XXX.mk make include files. * Complete this list with all the other tasks. ---------------------------------------------------------------------- 3.2 Assumptions This section contains some of the assumptions that the new build system make. If you break any of thees the results are... ``undefined''. * There can only be one level of image subdirectories, in IMAGES and similar variables. E.g. foo/img.png is OK, but foo/bar/img.png will break things. Note: It actually may be trivial to support this anyway. Time will show. ---------------------------------------------------------------------- 4 General usage of the new build system 4.1 The document makefiles Note: These are based on the current doc build system and may very well be redefined during actually implementation, but where possible the old variable names / meanings will be preserved. Each document Makefile have several options which can/should be set. MAINTAINER The maintainer of the document. Defaults to <doc@freebsd.org> if not set. DOC The name of the output file. Normally article or book. DOC_PREFIX The relative path to the root of the documentation source tree. Should be conditionally defined with the ?=3D operator so the us= er can override it if needed. Must be an relative path; that is may not include .CURDIR. SRCS The sources used to generate the document. HAS_INDEX Set to indicate the document have an index which should be handled. FORMATS The formats the resulting document should be generated in. IMAGES The per document list of images which are language dependent and provided in the tree. IMAGES_LIB The general list of images which are provided in the tree. IMAGES_EN The per document list of images which are language independent a= nd provided in the tree. SYMLINKS TODO. INSTALL_COMPRESSED TODO. INSTALL_ONLY_COMPRESSED If set, only the compressed version of the document will be installed. CHAPTERS Which chapters to build. Should be the chapter source files with extension. The source files Only for books. WITH_ARTICLE_TOC Add a Table Of Contents to articles. ---------------------------------------------------------------------- 4.2 User variables Thees variables should in general not be force set in the document Makefile, but the document Makefile may set defaults. DESTDIR This variable can be used to override the default tree under whi= ch files gets installed. This is like the normal DESTDIR variable which can be used used when installing FreeBSD. Warning: This is different from the current meaning of DESTDIR in the documentation build system, but since the current meani= ng conflict with the meaning in the FreeBSD src/ tree it should be changed. ---------------------------------------------------------------------- This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/. For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>. For questions about this documentation, e-mail <doc@FreeBSD.org>. --HeFlAV5LIbMFYYuh-- --rWhLK7VZz0iBluhq Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.2 (FreeBSD) iD8DBQE+04YT8kocFXgPTRwRApljAKCIPlm9oy+ZX2fl3nrlIf1xAdeYhACgraVS uHUztZ+BiM5UsBC65Dglhwo= =hVQx -----END PGP SIGNATURE----- --rWhLK7VZz0iBluhq--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030527153651.GM411>