Skip site navigation (1)Skip section navigation (2) 
Date:      Fri, 30 Jun 2000 03:50:12 +0100
From:      Nik Clayton <nik@freebsd.org>
To:        doc@freebsd.org
Subject:   On embedding 'library' graphics into documentation
Message-ID:  <20000630035012.A41595@catkin.nothing-going-on.org>
index | next in thread | raw e-mail 

[-- Attachment #1 --]
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
"<warning>" 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 <callout> 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 <userinput>.  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

[-- Attachment #2 --]
U\9co-test.tarWmo6WbذDS%vzp^;
(hHGRI}w(+[5Z`"{sXo9a[t{{O^wlwt{k
(5%o?+o(UOT|3vw|]\w֠Spz8:h28Apr~yz8ei&x29"^=?}
`΂[*w2y
Wc"$waMB,P.kaQ9IXQmi
smb2Mtx?ʡ8\hHhqshk 7xtt4չ.u~$gI^~ؿ.ˏ,_Rixa%7e}F߈؅F<77{;-CL8HWG6c:>ݭ#nEJԊ㳍~@JBD9s@O#Vrhklw}ֻJޟ.ڂfaj':9OSt깻G(,zIuÏz;!JYmOQ&hztVB#Ɇ'99i6AbOImYJT`Y"
DsjXrkX[/+=^ܣ-fRB]Ž¶jw$7눕arWtJZlԗ*<#VJ#%o)3|U7,9'+Juu;e|z0\umc,w-][a~I]O7tխ?XL6Zu	bhd촄T<34%ڔe:sF^_j'.<R<+LlZ\ys9ÕgB_\ҾZ7[?bUzT5хQD}8L"s)3J}/1$	|ڡ^U{!s!ŔIevLfF'1|K`'ZUœ>U"х)b%]4]]FuLj?s$$.]cKbni(@)%pg8LͨUZk|c4IͫieXbrHr~2JW?]%[W+VDP<j:B6y_XEPڅ!1u=lV~"g@-M=S0R91\5jRi򳢰Bew.t&>	e_Ē/a]N+]	fjN}ĭ*_kG|"VOTJK-RK-RK-RK-RK-B|(
[-- Attachment #3 --]
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 \

[-- Attachment #4 --]
#
# $FreeBSD$
#
# This include file <doc.imagelib.mk> 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

[-- Attachment #5 --]
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"
+

[-- Attachment #6 --]
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 @@
-<!-- $FreeBSD: doc/share/sgml/freebsd.dsl,v 1.14 2000/03/23 09:00:16 nik Exp $ -->
+<!-- $FreeBSD: doc/share/sgml/freebsd.dsl,v 1.13 2000/02/15 01:57:17 nik Exp $ -->
 
 <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
 <!ENTITY % output.html  "IGNORE">
@@ -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 "(??)")))))
+
+
         <!-- Understand <segmentedlist> and related elements.  Simpleminded,
              and only works for the HTML output. -->
 
@@ -124,7 +166,23 @@
               (normalize "legalnotice")
               (normalize "abstract")))
 
-      
+      <!-- The stylesheets need to know about the graphic formats we
+	   use.  In particular, PNG isn't supported "out of the box." -->
+      (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"))
+
       <!-- Slightly deeper customisations -->
 
       <!-- I want things marked up with 'sgmltag' eg., 
@@ -151,8 +209,10 @@
            Configure the stylesheet to behave more like John's. -->
 
       (element command ($mono-seq$))
+
+      (element application ($italic-seq$))
 
-      (element application ($bold-seq$))
+      (element filename ($italic-seq$))
 
       <!-- Warnings and cautions are put in boxed tables to make them stand
            out. The same effect can be better achieved using CSS or similar,
@@ -182,13 +242,15 @@
 
       <!-- Default to labelling Q/A with Q: and A: -->
 
+<!--
       (define (qanda-defaultlabel)
         (normalize "qanda"))
+-->
 
       <!-- For the HTML version, display the questions in a bigger, bolder
            font. -->
 
-      <![ %output.html [
+      <![ IGNORE [
       (element question
         (let* ((chlist   (children (current-node)))
                (firstch  (node-list-first chlist))

[-- Attachment #7 --]
Index: freebsd.dtd
===================================================================
RCS file: /home/ncvs/doc/share/sgml/freebsd.dtd,v
retrieving revision 1.4
diff -u -r1.4 freebsd.dtd
--- freebsd.dtd	2000/02/14 01:30:48	1.4
+++ freebsd.dtd	2000/06/29 19:28:24
@@ -23,12 +23,10 @@
 <!-- ..................................................................... -->
 <!-- Entities for element classes and mixtures ........................... -->
 
-<!-- Object-level classes ................................................ -->
-
-<!ENTITY % local.list.class "|FAQList">
-
 <!-- Character level classes -->
 <!ENTITY % local.tech.char.class "|HostID|Username|Devicename|MakeTarget|MakeVar">
+
+<!ENTITY % local.cptr.char.mix "|CO">
 
 <!-- OS Version attributes ...............................................
 

[-- Attachment #8 --]
\9imagelib.tar{PW`@"	>B
%a[A@EDA
PYTBQV*(UAPvQp⫨(
صLwnieo&s3s3sOØ !4U8DRT$z}T0BIbvREz &*YTƒwЈ(uOƟ쎼vAPĿg;Fπ!wGa6
H	xK[cOU2ތiv<&2+qddXL8&/ao(645ּmLugpdk4wxi,>uj#Vr]<8R$~~e
~G^,DcmyvH1Ab%;JRC3Ä[9
Q|LdDx#f2լT{懿Dh%YN0ehX5<ixOڸ_$o.	>{~[㐎J{>}fm,5{๧ERUد`'֟=֥t~iwl-yOb)ӎ!vzϣv5
SުrSú̈x깁yڲ܏X'4,.Wnb3 CqA) (
<7?O{qo9a`L2?Ae$N$4j<xqcJ^\o
=KŝǾf7KYn4,,n}o[03װ:
]
ņO*m|_#C'qHe8b8
Ӱ<B2
ZY;dyetG{T[_{8Kbk>
GJHVLݩ;zˍ*+_,XmYH2U$U 9zљ޽Z֤r:Zny%Qsoҏ,MC4K3,`0&3(Mj(o6K'~]_'!o?m`#K^~AƼ'u8Pglؖv]#`\VZ.i̻.7qMnӰj:,m!?YXxle]Ջ/;/V1>x~(PZ@h\[(YAs9O7w}I
M%dB@v[0"YZeQn͟<Cunsn^KQkkn'Wm\ڭĮk/gݸ`~wx+1)R2>{{S۹ea|~Rp8#`@#)	bi;i}0OtZJ,%◃493,  dLA;ׇw<W^"M1o:%r6UE7Sͮi~p)šn0rxҠ^b?-H*)4cFx"Xei@OKi@\K?cS\lZ+kIƬjߜJ8`S޶6^mY|;1uvOU{*ACo,n,34jx=t﫧?m'a04Q@ѼP5Nl?Qo?X%*h0;^2[rzگZv
6n˓~W6,!˂*Sh5r#T9җ[f5?~%AOf',a@(C AmI}'O/OH>ٟͨP,+,]oN٦~Je{dN[4fǪCm2?TW+77uLa646YodlhOTB$M:<r]*=އbwYFàQ<Fjk?Òɱ5(Suu
~6Oϵ%ZP
help

Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000630035012.A41595>