From owner-freebsd-doc Thu Jun 29 19:51:36 2000 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 60B2B37B68D for ; Thu, 29 Jun 2000 19:51:16 -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 DAA63484 for doc@freebsd.org; Fri, 30 Jun 2000 03:50:14 +0100 (BST) (envelope-from nik) Date: Fri, 30 Jun 2000 03:50:12 +0100 From: Nik Clayton To: doc@freebsd.org Subject: On embedding 'library' graphics into documentation Message-ID: <20000630035012.A41595@catkin.nothing-going-on.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="h31gzZEtNLTqOjlF" Content-Disposition: inline User-Agent: Mutt/1.2i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --h31gzZEtNLTqOjlF Content-Type: text/plain; charset=us-ascii Content-Disposition: inline How are we going to handle images that recur throughout different documents? [ It has come to my attention that apparently some of my messages have attracted a fan following, due to their extreme length. If that's the sort of thing you like then you'll love this. ] This gets a little bit complicated. As well as images that are document specific (screenshots, diagrams, and so on) we're going to have some images that will be re-used across the documents. For example, a picture of beastie holding up an exclamation mark next to "" elements, that sort of thing. And, of particular relevance to what I'm doing right now, "callout bugs". A "callout bug" is a little indicator next to a piece of text that you can refer to later on when you want the reader to understand exactly which bit of the text you're referring to. For example, mv [1]source-file [2]destination-file where [1] and [2] are my (rather crude) implementation of what a callout bug could look like. Later on in the text you might say. [1] The source file name. The mv command renames the file currently called source-file, which must exist when mv is executed. [2] The new filename. The mv command changes the name of the old file to destination file. If destination file exists when mv is executed it will be replaced by the old file. A real world example of where we use this is in the Handbook, in the section on PPP configuration. In there we use line numbers, but callout bugs would be equally appropriate. In particular, line numbers don't work where you want to refer to more than one thing on the same line, and breaking the line is impractical. I actually need to do this *now*, because I'm writing up an appendix to the DocProj Primer that includes various command lines you can run to do various things to the documentation, and I need to be able to refer back to portions of the command line in the following text. For more information, go to http://www.docbook.org/, read the online copy of The Definitive Guide, and the section relating to the element. You can do this without images -- putting (define %callout-graphics% #f) in the stylesheet does it for you. In this case your callouts are flagged much as I've done above, with [1], [2], and so on. This is OK, but not great. For one thing, it looks too much like the way footnotes are flagged. For another, the callouts are not visually distinct from the rest of the line -- you don't want a naive reader assuming that these are part of the command line you want them to type in. For these reasons (plus the fact we're going to have to confront this issue sooner or later when we put in admonition graphics and such like) I've started looking at how we share the same images across different documents. I've come to the conclusion that, at install time, we can't. That is to say, each document is independent from one another. I don't want one document to have to depend on another document for its images. Nor do I want to make each piece of documentation depend on another package that just contains the common image library. There are also issues relating to the position of the files in the image library. At the moment, someone could pkg_add a hypothetical image library package with $PREFIX set to something, and then pkg_add the Handbook with $PREFIX set to something else. Short of a post-installation script which attempted to find the image library and fix up the links in the document this is impossible to resolve. And a post-installation script would rapidly become a twisty maze of conditionals and special cases as it tried to work out where the image library had been installed. So, unfortunately, each document is going to have to carry its own copy of the imagelibrary (or rather, those parts of the image library that it uses) with it. This will bloat the installation area as soon as a reader installs more than one document, but (1) I don't see a way around that, and (2) the bloat is minimal. This is *not* to say that we can't have a common image library in the CVS tree, just that we can't rely on having a common image library for the installed documentation to use. However, at build, installation, and packaging time, each document will have to copy those images from the library that it uses to its own directory. Having decided to do that, things become somewhat simpler. Attached are a variety of patches and related files for inspection which do just that. 1. imagelib.tar.gz should be extracted in the en_US.ISO_8859-1 directory. This should give you an imagelib/ directory at the same level as the books/ and articles/ directories. It contains one sub-directory, for the callout bugs, and 10 PNG files. 2. co-test.tar.gz should be extracted in the en_US.ISO_8859-1/articles directory. You should get a co-test/ directory, with a Makefile and an article.sgml. 3. doc.imagelib.mk should be copied into the doc/share/mk subdirectory. 4. doc.docbook.mk.diff should be applied. I'll walk through these changes in a minute. 5. doc.project.mk.diff should be applied. 6. freebsd.dsl.diff should be applied (in doc/share/sgml). This includes a few changes that are not related to this -- you can ignore them, it's just stuff I'm testing in my tree, and doesn't affect this. In particular, only the callout-* stuff is used, you can ignore the rest. 7. freebsd.dtd.diff should be applied. This fixes a shortcoming in DocBook where callouts aren't allowed inside . I'll be submitting an RFE (Request for Enhancement) about this shortly. That should be sufficient for you to go in to the co-test directory and run make(1) to generate all the different output formats you want. Now, about those changes to doc.docbook.mk. . . We define and implements a new format, "html.tar". Previously, we've special-cased the html-split format, as we knew it would generate multiple files that would need to be managed. It was assumed that the other formats would only ever generate one output format. This is now not the case, as the bare "html" format still needs to be able to carry around all the images it will need to display properly. So the html.tar format is designed to do that. We also update the html-split.tar (and the new html.tar) format to ensure that tar is called to include the files listed in the IMAGELIB variable as necessary. We have to list the imagelib files as being dependencies for the various HTML output formats -- this ensures that if they don't exist, the simple rules in doc.imagelib.mk will copy them in to the current directory. The install rule is a bit more complicated, as we need to ensure that images are installed in to the correct subdirectory as necessary. And when building packages we need to ensure that the list of images is added to the PLIST. What about images for other languages? I don't think this will be a big problem. Some images will almost certainly contain text, or other content that will need to be translated. The easiest way to handle this would be a mechanism in doc.imagelib.mk that looks for the images first in the language specific imagelib/ directory (I assume each language will have one), and if it can't find it there then it copies it from the English imagelib/ directory. I'd do this now, but it's 3.50am, and I need to be up in about 4 hours time. . . Thoughts? N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery --h31gzZEtNLTqOjlF Content-Type: application/x-tar-gz Content-Disposition: attachment; filename="co-test.tar.gz" Content-Transfer-Encoding: base64 H4sICFUEXDkCA2NvLXRlc3QudGFyAO1XbW/bNhDO1+hX3NJi2LBEtPPmD1O8JXbSenBeEDvF CgwoaImOmUikR1JJg6L/fXeSKCtb0zUfWmCYDg4i8Y7He+Nzp1hvOWEdW/uKBLud3t4erAF0 e3vd5n9PHYBed7vX6Wx3u/jc7XR7u2uwt/YNKLeOG4A1JW8/K/dv/P8oxVX+T/mtmMtUfI0z up3O/u7uk/nvdrZ3fP67vZ1dXMH0d9ag0+b/q1Nwejg6m+Lf8eUBuvjriRHiaDIMtbkOguH5 4JcD4MbJOBVBcHJ+eXo4neDSwmVpEIzOJtPD8fjd4Pz04vJ4MjkeIqtePT8bv33ECoIXgL/J 5WACqbTOglsIkCqRdzLJeQqTV6djoCIkDneQYU1CvizEEh3nmVAuhMGCq2thUZPTwNUD6DlJ WFFtvZdpCnNtYgEcjJjlMk2CF3R4oT/WyqGegMw4AO9caK+zFEholHHUDnOjs+Lg2Ghrt/zx IImN5s8MNw/B6PTw1fF4dHSwHvM01bmzrBsu1XXN+KnB2X6Ss/MkZ/dJzl7BoRS9wwifjH7H 2L/8EA6uLoejy48sDMtfEIRSxWmeCNh4+WEl/ZHZBTeCZbcMfQuXRt+I2IXZ7Uaw1tL/hzz+ N+/BN8b/3f29/Rr/93vYC7rb+zst/n8Tir5DTJi+vTj2SAgXV0fj0QA2thirmgFjw+kQhjo+ 0voW3uyE3a0jbkUCx+8RSq3UirHjs41+QNkMokoRvdLzQvBEmJIZOemQc6hAvOfZEk+rhCNW cmgPa2yid4vA1H20f6CzjKvE1rtK5pIb3p8upAXagmYBtxZhu2onDzqHBb+jloM5T1N0gADe 6rm7RygsehKuSRWUdUnMiHqK4pnoO/HeIUrGBJeElhGrWbDUxm2CkLjDwOwBT1HJJmh6rnTl VqrrQiPJhgAnOTlpNkFiT7GVoUltqFmZhdza4EqbVGDzWSINuqmNRAdzheFqWMtya1iqsVuw hqGb2C8Lpys9XsMD3KMtAmZS8UJdEaaZEKoRq8KOwrZqdyTUHTf9i8Pp64iVz+jYYXKDV6p0 lbsFuQZKxMJabJjUl5sq7AOGPAsjVqSuSiMlb7vvDykzfFXE7zcsisc5JyvKSuoH63V1qDuB ZYUbfM3ipPB6is3/B60wz9xcl8PCj7WyddxtYyx31f8es5stXZhbYX6GiP5Jtcxd/wZPh603 oHS8yNWthT/w9FiDTA42/Fp1CbZiaGSg7LSErFQ8MzSIJdbalGU6ydEaFnOMsb5GhV5ftfKl 6moFnxcnD/4umzzLUhr8PCtMbFobXIh5cx0U45TnOcOVxcxnFZ9CXw5c/fKZtNbSvlo3+hFb BT9iVXoCzFQ1BNGFxdRRFsoFRBOBv7l9lJD1FThMliKWcynK0TNKpROGp30vHDG/AiSeCXyh 2qEbs15VrHvAIXMhhLObxZRJZYanAx6PdpL0TMC9kQ6hEd/8vojPZkbc9SfT4fnVFDGufK1L n7xglRvk4yedWlXFkz5VIhXk0YUpB2IlCF00EIThXQy9XdMFRnW1iwDHiD9zBIYkJC5dFGNL jPJihW6vgOZpjiiB4EAp5iXuzshwsmc4mUzGzahVWvGSa5V8qZLqGmMbqra7hTRJvc2rae62 ZVhicprC8LxI+3J+Ms7zHINKAFfVxz8cXSXAW1fkASuawFb5RPi2UH/fPMvM5s1qmDpC0DZ5 jF9YRQFQ2oUhMeB1PYpsueBW2n6to4gbIrlnlN9AhJjU/ouPLU09C1MwUuAVOeq3MY4Dm9Xn HN0CXJqJwjWvHKuv/qRqpLPWUgaxAGnK8rOisEKMz+QLZRp3wi50niY+CWVfxJIv+mFdTqsr XcwJlb6k0WYL5GpOAgWcfdr49fq5xK0qD6zuX+Vr3f3KRxx8IlZPVO33SksttdRSSy211FJL LbXUUksttdRSSy219OX0F0J8mR8AKAAA --h31gzZEtNLTqOjlF Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="doc.docbook.mk.diff" Index: doc.docbook.mk =================================================================== RCS file: /home/ncvs/doc/share/mk/doc.docbook.mk,v retrieving revision 1.11 diff -u -r1.11 doc.docbook.mk --- doc.docbook.mk 2000/04/29 07:46:15 1.11 +++ doc.docbook.mk 2000/06/30 02:41:50 @@ -51,15 +51,18 @@ DSLHTML?= ${.CURDIR}/../../share/sgml/freebsd.dsl DSLPRINT?= ${.CURDIR}/../../share/sgml/freebsd.dsl + FREEBSDCATALOG= ${DOC_PREFIX}/share/sgml/catalog DOCBOOKCATALOG= ${PREFIX}/share/sgml/docbook/catalog JADECATALOG= ${PREFIX}/share/sgml/jade/catalog DSSSLCATALOG= ${PREFIX}/share/sgml/docbook/dsssl/modular/catalog +IMAGELIB?= + 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 pdb +KNOWN_FORMATS= html html.tar html-split html-split.tar txt rtf ps pdf tex dvi tar pdb # ------------------------------------------------------------------------ # @@ -115,6 +118,9 @@ .elif ${_cf} == "html" _docs+= ${DOC}.html CLEANFILES+= ${DOC}.html +.elif ${_cf} == "html.tar" +_docs+= ${DOC}.html.tar +CLEANFILES+= ${DOC}.html ${DOC}.html.tar .elif ${_cf} == "txt" _docs+= ${DOC}.txt CLEANFILES+= ${DOC}.html ${DOC}.txt @@ -166,13 +172,13 @@ all: ${_docs} -index.html HTML.manifest: ${SRCS} +index.html HTML.manifest: ${SRCS} ${IMAGELIB} ${JADE} -V html-manifest -ioutput.html ${JADEOPTS} -d ${DSLHTML} -t sgml ${MASTERDOC} .if !defined(NO_TIDY) -tidy -i -m -f /dev/null ${TIDYFLAGS} `xargs < HTML.manifest` .endif -${DOC}.html: ${SRCS} +${DOC}.html: ${SRCS} ${IMAGELIB} ${JADE} -ioutput.html -V nochunks ${JADEOPTS} -d ${DSLHTML} -t sgml ${MASTERDOC} > ${.TARGET} .if !defined(NO_TIDY) -tidy -i -m -f /dev/null ${TIDYFLAGS} ${.TARGET} @@ -180,6 +186,11 @@ ${DOC}.html-split.tar: HTML.manifest tar cf ${.TARGET} `xargs < HTML.manifest` + tar uf ${.TARGET} ${IMAGELIB} + +${DOC}.html.tar: ${DOC}.html + tar cf ${.TARGET} ${DOC}.html + tar uf ${.TARGET} ${IMAGELIB} ${DOC}.txt: ${DOC}.html w3m -S -dump ${.ALLSRC} > ${.TARGET} @@ -193,9 +204,6 @@ ${DOC}.rtf: ${SRCS} ${JADE} -Vrtf-backend -ioutput.print ${JADEOPTS} -d ${DSLPRINT} -t rtf -o ${.TARGET} ${MASTERDOC} -${DOC}.doc: ${SRCS} - ${JADE} -ioutput.print ${JADEOPTS} -d ${DSLPRINT} -t doc -o ${.TARGET} ${MASTERDOC} - ${DOC}.tex: ${SRCS} ${JADE} -Vtex-backend -ioutput.print ${JADEOPTS} -d ${DSLPRINT} -t tex -o ${.TARGET} ${MASTERDOC} @@ -270,7 +278,7 @@ .for _curformat in ${KNOWN_FORMATS} _cf=${_curformat} .for _curcompress in ${KNOWN_COMPRESS} -.if ${_cf} == "html-split" +.if ${_cf} == "html-split" || ${_cf} == "html" ${DOC}.${_cf}.tar.${_curcompress}: ${DOC}.${_cf}.tar _PROG_COMPRESS_${_curcompress} .else ${DOC}.${_cf}.${_curcompress}: ${DOC}.${_cf} _PROG_COMPRESS_${_curcompress} @@ -283,8 +291,7 @@ # Install targets # # Build install-* targets, one per allowed value in FORMATS. Need to -# build -# two specific targets; +# build two specific targets; # # install-html-split - Handles multiple .html files being generated # from one source. Uses the HTML.manifest file @@ -320,12 +327,21 @@ @if [ -f ${.OBJDIR}/${DOC}.ln ]; then \ (cd ${DESTDIR}; sh ${.OBJDIR}/${DOC}.ln); \ fi - +.for _curimage in ${IMAGELIB} + ${INSTALL_DOCS} ${_curimage} ${DESTDIR}/${_curimage:H} +.endfor .for _compressext in ${KNOWN_COMPRESS} install-${_cf}.tar.${_compressext}: ${DOC}.${_cf}.tar.${_compressext} @[ -d ${DESTDIR} ] || mkdir -p ${DESTDIR} ${INSTALL_DOCS} ${.ALLSRC} ${DESTDIR} .endfor +.elif ${_cf} == "html" +install-${_cf}: ${DOC}.${_cf} + @[ -d ${DESTDIR} ] || mkdir -p ${DESTDIR} + ${INSTALL_DOCS} ${.ALLSRC} ${DESTDIR} +.for _curimage in ${IMAGELIB} + ${INSTALL_DOCS} ${_curimage} ${DESTDIR}/${_curimage:H} +.endfor .else install-${_cf}: ${DOC}.${_cf} @[ -d ${DESTDIR} ] || mkdir -p ${DESTDIR} @@ -370,6 +386,9 @@ @cp HTML.manifest PLIST .else @echo ${DOC}.${_curformat} > PLIST + @for imagelib in ${IMAGELIB}; do \ + echo $$imagelib >> PLIST; \ + done .endif @pkg_create -v -c -"FDP ${.CURDIR:T} ${_curformat} package" \ -d -"FDP ${.CURDIR:T} ${_curformat} package" -f PLIST \ --h31gzZEtNLTqOjlF Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="doc.imagelib.mk" # # $FreeBSD$ # # This include file handles pulling in images from the # imagelib/ directory as necessary. # # Each document that wants to use one or more images from imagelib/ has to # list them in the IMAGELIB variable. For example, a document that wants to # use callouts 1 thru 4 has to list # # IMAGELIB= callouts/1.png callouts/2.png callouts/3.png callouts/4.png # # in the controlling Makefile. # # This code ensures they exist in the current directory, and copies them in # as necessary. # IMAGELIB_DIR?= ${.CURDIR}/../../imagelib CP?= /bin/cp MKDIR?= /bin/mkdir .for _curimage in ${IMAGELIB} ${_curimage}: ${IMAGELIB_DIR}/${_curimage} [ -d ${_curimage} ] || ${MKDIR} -p ${_curimage:H} ${CP} ${IMAGELIB_DIR}/${_curimage} ${_curimage} .endfor --h31gzZEtNLTqOjlF Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="doc.project.mk.diff" Index: doc.project.mk =================================================================== RCS file: /home/ncvs/doc/share/mk/doc.project.mk,v retrieving revision 1.2 diff -u -r1.2 doc.project.mk --- doc.project.mk 1999/09/06 06:53:39 1.2 +++ doc.project.mk 2000/06/30 02:26:06 @@ -67,8 +67,13 @@ .if ${DOCFORMAT} == "docbook" .include "doc.docbook.mk" .endif +.if ${DOCFORMAT} == "html" +.include "doc.html.mk" .endif +.endif # Subdirectory glue and ownership information. .include "doc.subdir.mk" .include "doc.install.mk" +.include "doc.imagelib.mk" + --h31gzZEtNLTqOjlF Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="freebsd.dsl.diff" Index: freebsd.dsl =================================================================== RCS file: /home/ncvs/doc/share/sgml/freebsd.dsl,v retrieving revision 1.14 diff -u -r1.14 freebsd.dsl --- freebsd.dsl 2000/03/23 09:00:16 1.14 +++ freebsd.dsl 2000/06/30 01:36:35 @@ -1,4 +1,4 @@ - + @@ -45,6 +45,48 @@ ;; Write a manifest? #f) + (define %callout-graphics% + ;; Use graphics in callouts? + #t) + + (define %callout-graphics-ext% + ;; The extension to use for callout images. This is an extension + ;; to the stylesheets, they do not support this functionality + ;; natively. + ".png") + + (define %callout-graphics-path% + ;; Path to callout graphics + "./callouts/") + + ;; Redefine $callout-bug$ to support the %callout-graphic-ext% + ;; variable. + (define ($callout-bug$ conumber) + (let ((number (if conumber (format-number conumber "1") "0"))) + (if conumber + (if %callout-graphics% + (if (<= conumber %callout-graphics-number-limit%) + (make empty-element gi: "IMG" + attributes: (list (list "SRC" + (root-rel-path + (string-append + %callout-graphics-path% + number + %callout-graphics-ext%))) + (list "HSPACE" "0") + (list "VSPACE" "0") + (list "BORDER" "0") + (list "ALT" + (string-append + "(" number ")")))) + (make element gi: "B" + (literal "(" (format-number conumber "1") ")"))) + (make element gi: "B" + (literal "(" (format-number conumber "1") ")"))) + (make element gi: "B" + (literal "(??)"))))) + + @@ -124,7 +166,23 @@ (normalize "legalnotice") (normalize "abstract"))) - + + (define %graphic-extensions% + '("jpg" "png" "tex" "gif")) + + (define %graphic-default-extension% + "png") + + (define preferred-mediaobject-extensions + (list "tex" "jpg" "jpeg" "png")) + + (define acceptable-mediaobject-extensions + (list "gif" "bmp")) + + (define acceptable-mediaobject-notations + (list "GIF" "GIF87a" "GIF89a" "BMP")) + (element command ($mono-seq$)) + + (element application ($italic-seq$)) - (element application ($bold-seq$)) + (element filename ($italic-seq$)) + - - - - - + +