Date: Sun, 18 Feb 2001 20:02:46 +0000 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: Image support: as close as I'm going to get Message-ID: <20010218200246.A453@canyon.nothing-going-on.org>
index | next in thread | raw e-mail
[-- Attachment #1 --]
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.
<mediaobject>
<imageobject>
<imagedata fileref="foo" format="PNG">
</imageobject>
<textobject>
<literallayout class="monospaced">
...
</literallayout>
</textobject>
<textobject>
<phrase>Some text</phrase>
</textobject>
</mediaobject>
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 <caption> element, if appropriate. It may also
be necessary (depending on context) to wrap the <mediaobject>
inside a <figure> 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
[-- Attachment #2 --]
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/}
[-- Attachment #3 --]
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)))
]]>
<![ %output.print.pdf; [
[-- Attachment #4 --]
:*:test.tar \0*qumDQP:X C2H
{Y{]{Ŏ
biM swι{V2y>NrwlRPg;gǙ<]ݝ]=<wOv
?1F@Q
/#0|VoxHw?ҕ?KT ށ](k'n
pr
@p*98<r:'A0wAl(-+w(tC`Pq>Dk:ꌬex4Q9G&(꣤(wCg/~e턯*-"
I(#XoZ'vxEC9pA ~#"X
KpL<2Z L/'*eʿv~.6Gp-
S!AG˨Y
gfH, WմZ`AkMd
Fo1pŋ('pzVe4+(2+wkHl$X0PġX8pDDCG3p#&w?k;Ww \\\=TK(5rbt#:l߾]wxH.1ܞrLh頧Z*@vزR-_RQQ*u
1G.ykPhGv үkhh NzM%Ti4h #-i[u2_@`'GGJ#SiLjn9V;
6 Qo q9jO"7ѿҿ?u
eC5{S(*d
V \7W"wGuяRRGި3ϸ &o6~fN;s.,dYd~gw݇O? ?gN^8s~\~:ܾ~=ytɣ'IƋy{y/KgE5ňʕ+-ԣ7~=jS7g5ofVDURd*f߿V1+-*ܱz]KQbDSf
jb
s}7sjܩzlm)zzW8Y1=WQ\yB7[Vt^垯-?*STl~fo\lxPT(~,*
k+RT0+*(JfzՆWȪP=Q{)6T(WU**LW<>Y1Bm +LXj2Y
^U5h!Q?Tsfj7뗚VN1<ⓩ*VxƩ3OZeJYz
3QHB(<GEö?*K.cU~[|Ņ?Q?9 -B9jS:F~Q]uޕ~FvZo7*sa.!M@pVE6Ț黥RĚޤ/.iKWӗe-ȧ^}8*v^۱G^y[V+7<{loai|}fT48;cU6Oxsz?[}.
nt(=%euuWL&%~[:g1MݫV-*tIɜV_YcIGv_}z{qQ957ovXOzߚcߥNΟ鐽>1mDʷF,zw՞/ޝy:mqJ썃ҒrS+jXe5ܻfs~합a#'wf#$/+SLM9*aOfBMq}Jk[ͳ[g|~z|4r_tP.f\B~Ewd}4qfE]Fɭk'֜E |b>T/2}.N+7
ռTתq+%?7ÏcǾfRˊӖ>z:/33~XNRVrw>ܫSckS(bjV)WM3F:?Hzg9MՂTsU_R*̺ymX2L0N
3;'\)\/N̷RFUI_.{kƦy u>A':}rчij[U|%sWɞ}źu*<ljW揯}`9[*-Le?=FƭeY4fZ*,}s(;1^aىC|
M|9:v;nξkcϗ|^oҢTՌ.л'6]tɜ+opjjqj⚾r͌=WtgsFlܙHk~Nw_V|3Y/=Yߣ{ve|,ܽG߿"c>;
sb\O#IwMڱng[G>)J>|]\˹^*YvÉvMɸt#8?8>D#.իJ;Ɣ6i5;j.ߕ+<(^Ģk>wnj/4WJZܑ;Qx\bMRI\BqKR(-muޥ>PQ^Q>96hʺ7
ScflLoߍ_<{>Fvw+Jp|Za 4y7wiۭcwo=+za洎#,*>QY~}y.Zzy}ZUsQWb},7wVV^@s5u:6FPsf:/HɁŏ/vlpEݽA%4sb^ѡ)FM<YnDW4}:)<gy럫Qyy3{5{˶̾:X͙l9dvе6<kN7Nt5o_wm%y>W2^gi&kũgX[Bf<Yp5)W_
!QQ-7FfZ/5&W˛3nl͵i~.l͉7[ nO3O Vz)s&Oʪߩa!W\\Tea}I29mֲ5F5cͧx+kҔFŧaOҳk۲vyXʡKRzÆU>٬;ܼQG:CvSWʋ9Kn|wLa~6x0z9S|{n餫:~ѡ9ZjGf6ZpJUwҙUǣnWޤe'zh§/
U3bm7[7FsUߣM~%]~JWש<Ҙ6Mlrk|?ḽt5vGۮ~?xm|"j[nQ%sR[疻C*q.#:~ysE|滧?lsV0L0G^0[sMq~G]1sZz@ԧɒM5M%Yxk;B힝⎧UOp C=3whl^xb'2Kw"L)&|`KIPpԜbhU{>kݺQo>M~Cd*<_{fH2gwjN#k5c?ncMn]]05,74xE۬m&vTm!Z]s͓Wm=~eݏC3tōxإoǍ65c)ZC}53h6|k|Ֆg')k|^vpH5/S&-IgτZ+6\:V+/&ΙZJI=Ulc=ᵓ7=ړۡdgij̱?[}jVH\v,ZySQO:E^W3>Ň%u6LnѶLCnS^2_4.XP9g|ЎK~PPK֭K9{S{;νÕ뙕_.3Z+/C/j_82`vq1 4.9ty\RأbirTWWnߥ튦;Xl C]GFUix MjA9
Z왙sғdž
Rs~}6h|K<Q}r.!/>qo식y?9{6z<a8k77a7vvՎ3=xs5K9{jH-zTĽ_\Jn:ugZykTxg_跻oozʮSzFkm-Ƕ55<qtK9}67Y݁6P
QwQkw&挈w̕[5oW)~,zm쾤!^Wusc{KBլ[x*v&;wV?vΎ[Ev6!Dmn{恗.\ZSmƭ?x뒐~|;wJA-Wxb
5<zu֪f d~VJ?Xnf$zLjx>_^ΎέZv>6uoE3dF7>>lo\<zuU7A>=﷾Y?.Hw82n}ݞj0y536l:/w:}}u;[V՟'g,Yz[>{{;Ǚ563Fs/?W!V0uOԟd-6){L~w?nsڒƓOz⁹}G-YtM5tjgY]lqӸwr+mqsW}i'oyZkϢ\8678mk2$lߗ-or7ϼrכ{rk\.
U0۞{#I.cCeu;zw?3ե*
\6)KU/3f?p=:`^K=6jUz.H[zJ99i5\%^VvYsM=w{λ]zka7B[,Zŋn6_I:gE>]^͘>;wJlۏ矸khun6[Iƽ`Qd3uln_Fͯy*4߸xbeo[MyiXÛmQݢ_u9R;8tag҅j$vʰ`xDޗ=8.rF5OYkҐ醪Gi<vQ<.GyO̗
sn`A~խVoXUN=[8MZ^iBaFsa#V[_?uRH#/oVh1G AvOz[x59j3`!u6Wbpxc3NٙPæ;n2v%9\gw;=r~
[=z'ք^MM߫;Y7V6x
W{D#n=?h3 sL3rku(9hyFN|/WbUf+N59EoM*8$"˽s<M_ܦ-xxgZ[5Ԯͫϸe7d!|Sy8lҬRK7"{q2'=ehp=V!ԞP28Ums
Sk˭g:$w!*T:Z>xGK*nD}pJkRȆZ9Þٻhu];qZzU?uaDub';y?:۵6TOe9!Vyه>77ҊSWoH?mȊvn
|an.]:-%C1hi2_<$5cغ.oyxn)lp
LfōvJO06r8rzDhSY;{ؕטfO/hxS:|yQc۴F~]'~K93(D}ǂK{/+PWz7Jn^>j;KjS40]ېڶrxVK^\{Joл~{s2$/zZ]+XPpёEUz_{l~iVwPϿ?7eSaw
gj]M٨Ӟ}bz/uހO4w\31M笩71<ziKuNX91flܣׄ#Ε3F&po aC\oX3ORt_qfؕת6ݷE!6wԔ]q'_Ჷgq#6]Rn&sy:NO/>7ςO請UmV87J)V5QmNA/6>쯳>Kz]J5^6W'c~s
!ɾsT~WZnؐ?Ϲ/tŃ{)?48u?H{Gdm<oe#'N&wK?+bZ=~#3$ UdqIx[W>e{|wy4WħWy3ʹ+7\mwB|ËO)7ͮXV8gMfL?{o$=O)ZQYi7XMH,YT&y`ȋKSc2J^y+16Hhq.{2¦s>K4څ7DVY[j|/G md%So~HW]_aȡo+9kp{M>?t~椂[i3.!C|EOJ%֏h~wWy_[_m8z|/$Oz?>pw>LvCwq^cd]MNݱߴ(%anm5"jSha+
Ku50eylmVz;7=~X/tItڃO:9.Y|SXѽO'mIϮ̪IC}{-YꏟmEfZ@}6C_Ltd^*nkfl[><nK6}rI{揰\oC×I;M|c~aĕ79u(T4**i?h!M^WnaYKkoOylC}O=8_x-<ieL]qM]_Uz0"jTXv.nk}ܬUEІ
MGλQ#~WyI?Ϩ:wnӐii??<+cwO-+R]4pUXiAÏ]wѷh%mͺZ50!iuwqSEnC
\mxο-yܱRyzumox-ѡC;]sAl}vC
&|빸n)|.<
i:ޤćG=$فvTk?,{y#<t/e\?tUǮWJٵGm/9e[lk>spLinnם;rpO?ȭ
sXZa9<̈vgvwK[?baM<5لz~o[.˪}6?lY&o;6<9=l/;qJ*n}!u˯|_.gDwZ|i
[V[lhmW7gCsi9/KܘREw[\m8>龻+:,5R=hK<-δ!;1d籁+k4iq`IА}VÑ,b6t̍#ӂk2A*}i3kZv.vӟZgJ1j~3ş9۲o6ݖY3^'GsfݧE*Ϻյb͙<g)
xߪwܻ'>t?y
bC|훼)z`[66nJ6}<ybQQO90WV}W'fP#Aţ^J7m_Z>!#T Ǖ7>ԛQ2um>|bV
)
[ߚs+ϺWl{ϸQ珏\MΞ߿J_1M/ßrr6jZ'l+طI<2)b$U;/{U
lɀ_cTvmзCé#ܓSr]v7u#ހ'R*yXӛM}e^t1$$yrpW Ҵqs7h<8Fk{/Nu=)x
w/
mk
4fΝw>}1e/;e^O1]Ma^/7ƳY8k]5**z}1û-Ӿ4~l0SMyjzZ-Ϻ|
e_J:7PN?Oӑ
WV}%~=ORo{:Ϧpw=i͵;yusfx;Xl'q]]z-e:'d*ߑAwVdzg+~Ƚx2<GKrw0U3)PsU7ew5Jή5kssg~yt6hD籥gz~l8dM/'ԹF|6km3 X|mmg^GjyPgmnzlkiޏ~ѶcVtI==&!kkuϋCw~yi!yɩ9[^3gɪ}Ka{qOG=أc[}y[tߪO3g9fKI5yI`=
k$Hӿ-N[B1`A~yvMO%]qlin#~xAwaO;3|xװHs6n)z34.7$waAQU7ٟl6lMX]hU:sά$mŔgvW_N^M.uղ
<dn?
=+)* -ꜭ4AE߭m_2
Ōx?yM:.hgVHZ~ó˵BԄ|JHTa
|mUVCd8X1kS+G^^
aI)Er@:ndw!}ZaɺgK˼Q7n?_8%֭[=]jxHTuJfGW[)48oɞ;\.>}*JϨD]vOvnb3toc<$Oͅ30)CicF{lLicFj cBUQ&P F 5`Ph;w/v(o
SU.9gV!
b)oL:5ݟt<ځ_Б:6Uɽ(Gg<MW2:#tjU`A`f"p&ɾ;i8JK
l7N*NBuxipVFߜOpjJ_^>\up_fy7sƺ#kgy7;/vס}ʇWщsC
]\}nҍpu߾]7+;7Qvodz:i^#:ioRvoյص[٩kWt2-.ud<x[Ս[ލ˻t#^ oyY}{"Q2:c(=QZ.1rkXr/.Mx=Ұztpqw˵C{_ u.мeN*=5V|\~&pF#iFr<w!زrPc^XUחuXm
\岢(.F.2Fih |-ee&~l`3ph,.0j?PGۿ cK,ڃ9?&=2@(w2p
݅bTQo
&
E1GGe#,Y-KH%5DꌌQ UdOM<kq+!
|Ro>s\Z<a?Jo<@*
i!*=1*u40(wi)wvo
C;7 $:LA>N6VI/nx| #x Yԃ ]N ̗4G(\@BhQ)[?;rp`CfS(SxG[]]s;wsvTn\\k%r|Aeb(P]ܽ]@)%LMGv:K+mAO$<