From owner-freebsd-doc Mon Feb 19 1:14:59 2001 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (unknown [194.128.198.234]) by hub.freebsd.org (Postfix) with ESMTP id 6D84837B401 for ; Mon, 19 Feb 2001 01:14:25 -0800 (PST) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.11.1/8.11.1) id f1IK2kD00697 for doc@freebsd.org; Sun, 18 Feb 2001 20:02:46 GMT (envelope-from nik) Date: Sun, 18 Feb 2001 20:02:46 +0000 From: Nik Clayton To: doc@freebsd.org Subject: Image support: as close as I'm going to get Message-ID: <20010218200246.A453@canyon.nothing-going-on.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="AhhlLboLdkugWU4S" Content-Disposition: inline User-Agent: Mutt/1.2.5i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --AhhlLboLdkugWU4S Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Hi folks, Executive summary: I think I've got image support in the doc toolchain to the point where it can be committed, and textproc/docproj can be updated to pull in the dependencies. Attached are patches to the .mk files and the DSSSL stylesheet to support this, and what follows is a discussion of the requirements, and the steps necessary to add an image. I've also attached a quick demonstration article. The support that's in at the moment used ImageMagick, which has a long list of additional dependencies, which are think are too onerous for the average author. Remember that the source formats for images in the repository are PNG and EPS, I've got the requirements list down to: Output Format HTML Postscript PDF -------------------------------------------------------------------- graphics/eps2png graphics/netpbm print/tetex print/ghostscript6 graphics/tiff graphics/jpeg graphics/jpeg graphics/png graphics/png I'm ignoring RTF for the time being -- I don't have easy access to something that can preview the output. For HTML output, eps2png is required to convert EPS files to PNG, suitable for putting on a web page. eps2png in turn requires Ghostscript and it's support for PNG as an output format. For Postscript output we need to be able to convert PNG images to EPS, which requires graphics/netpbm, and it's list of dependencies. For PDF output we need to be able to convert EPS to PDF. teTeX (which the user must already have installed) has epstopdf, which does this nicely. All told, that's another 10MB for a user to download. Over half of which is Ghostscript. If anyone knows a simpler way to convert EPS to PNG, please let me know. So I propose listing graphics/eps2png and graphics/netpbm as requirements in textproc/docproj. Moving forward, we might conditionalise this on a 'want graphic support' tweakable knob, but frankly, I want to get this support in now, and get people to start using it, and refine small details like this later. Using images in documentation ----------------------------- Very simple (after applying the attached patches, and installing the applications above). 1. Create your images as either EPS or PNG files, depending on whether they are vector or bitmaps. 2. List each image in your document's Makefile in the IMAGES variable. For example, if you foo.png and bar.eps, write IMAGES= foo.png bar.eps 3. Use the following markup to include an image in your document. ... Some text The important entries are ImageData Points to the image. The 'fileref' attribute should contain the image file name (without the extension). The 'format' attribute should contain the image's *source* format, either "PNG" or "EPS". Case is important. TextObject #1 Will become an ASCII art representation of the image when/if the document is built without image support. Please use your best efforts to do this. TextObject #2 Will become the 'alt' attribute of the 'img' element in the HTML version of the document. You can also add a element, if appropriate. It may also be necessary (depending on context) to wrap the inside a
element. 4. Run make(1). Comments appreciated. 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 --AhhlLboLdkugWU4S Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="doc.images.mk.diff" Index: doc.images.mk =================================================================== RCS file: /home/ncvs/doc/share/mk/doc.images.mk,v retrieving revision 1.6 diff -u -r1.6 doc.images.mk --- doc.images.mk 2001/02/12 17:03:54 1.6 +++ doc.images.mk 2001/02/15 17:38:22 @@ -68,25 +68,14 @@ .for _curimage in ${IMAGES_GEN_PNG} ${_curimage}: ${_curimage:S/.png$/.eps/} - convert -antialias -density 108x108 ${_curimage:S/.png$/.eps/} ${_curimage} + eps2png ${.ALLSRC} .endfor .for _curimage in ${IMAGES_GEN_EPS} ${_curimage}: ${_curimage:S/.eps$/.png/} - convert -antialias -density 108x108 ${_curimage:S/.eps$/.png/} ${_curimage} + pngtopnm ${.ALLSRC} | pnmtops -noturn > ${.TARGET} .endfor -# -# Trial and error here with the options to ImageMagick. -# -# -density seems to smooth out the images. Something to do with the source -# images being different from the 72dpi that ImageMagick wants. -# -# -crop 0x0 forces the images to be trimmed to the minimum size. Otherwise -# each image takes up a full page, which is bad. -# -# epdf: forces the output format to be encapsulated PDF -# .for _curimage in ${IMAGES_GEN_PDF} ${_curimage}: ${_curimage:S/.pdf$/.eps/} epstopdf ${_curimage:S/.pdf$/.eps/} --AhhlLboLdkugWU4S 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.21 diff -u -r1.21 freebsd.dsl --- freebsd.dsl 2001/02/13 19:21:31 1.21 +++ freebsd.dsl 2001/02/18 19:55:58 @@ -184,6 +162,39 @@ filename (string-append filename "." %graphic-default-extension%)))) + ;; Including bitmaps in the PS and PDF output tends to scale them + ;; horribly. The solution is to scale them down by 50%. + ;; + ;; You could do this with 'imagedata scale="50"' in the source, + ;; but that will affect all the output formats that we use (because + ;; there is only one 'imagedata' per image). + ;; + ;; Solution is to have the authors include the "FORMAT" attribute, + ;; set to PNG or EPS as appropriate, but to omit the extension. + ;; If we're using the tex-backend, and the FORMAT is PNG, and the + ;; author hasn't already set a scale, then set scale to 0.5. + ;; Otherwise, use the supplied scale, or 1, as appropriate. + (define ($graphic$ fileref + #!optional (display #f) (format #f) + (scale #f) (align #f)) + (let* ((graphic-format (if format format "")) + (graphic-scale (if scale + (/ (string->number scale) 100) + (if (and tex-backend + (equal? graphic-format "PNG")) + 0.5 1))) + (graphic-align (cond ((equal? align (normalize "center")) + 'center) + ((equal? align (normalize "right")) + 'end) + (else + 'start)))) + (make external-graphic + entity-system-id: (graphic-file fileref) + notation-system-id: graphic-format + scale: graphic-scale + display?: display + display-alignment: graphic-align))) ]]>