doc/README.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html lang="en">
   3 <HEAD>
   4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5 <TITLE>XPM README</TITLE>
   6 </HEAD>
   7
   8 <body>
   9 <h1 align="center">XPM README</h1>
  10
  11 <h2>Contents</h2>
  12
  13 <ol>
  14 <li><a href="#sec1">What Is XPM?</a>
  15 <li><a href="#sec2">Where to get XPM?</a>
  16 <li><a href="#sec3">Documentation</a>
  17 <li><a href="#sec4">Installation</a>
  18 <ol>
  19 <li><a href="#sec4.1">With imake</a>
  20 <li><a href="#sec4.2">Without imake</a>
  21 </ol>
  22 <li><a href="#sec5">SXPM</a>
  23 <li><a href="#sec6">CXPM</a>
  24 <li><a href="#sec7">Other Tools</a>
  25 <li><a href="#sec8">Discussion</a>
  26 <li><a href="#copy">Copyright</a>
  27 </ol>
  28
  29
  30 <h2><a name="sec1">1. What Is XPM?</a></h2>
  31 <p>
  32 XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
  33 <p>
  34 Here is provided a library containing a set of four functions, similar to the
  35 X bitmap functions as defined in the Xlib: <code>XpmCreatePixmapFromData</code>,
  36 <code>XpmCreateDataFromPixmap</code>, <code>XpmReadFileToPixmap</code> and <code>XpmWriteFileFromPixmap</code> for
  37 respectively including, storing, reading and writing this format, plus four
  38 other: <code>XpmCreateImageFromData</code>, <code>XpmCreateDataFromImage</code>, <code>XpmReadFileToImage</code> and
  39 <code>XpmWriteFileFromImage</code> for working with images instead of pixmaps.
  40 <p>
  41 This new version provides a C includable format, defaults for different types
  42 of display: monochrome/color/grayscale, hotspot coordinates and symbol names
  43 for colors for overriding default colors when creating the pixmap. It provides
  44 a mechanism for storing information while reading a file which is re-used
  45 while writing. This way comments, default colors and symbol names aren't lost.
  46 It also handles "transparent pixels" by returning a shape mask in addition to
  47 the created pixmap.
  48 <p>
  49 See the XPM Manual for details.
  50
  51
  52 <h2><a name="sec2">2. Where to get XPM?</a></h2>
  53 <p>
  54 New XPM updates are announced on the comp.windows.x newsgroup, and on the
  55 "xpm-talk" list and you can always consult the XPM Home page at <a
  56 href="http://www.inria.fr/koala/lehors/xpm.html">http://www.inria.fr/koala/lehors/xpm.html</a>
  57 <p>The latest "official" XPM release can always be found at:
  58 <br>Boston, USA: <a
  59 href="ftp://ftp.x.org/contrib">ftp://ftp.x.org/contrib</a>
  60 <br>Sophia Antipolis, France: <a
  61 href="ftp://koala.inria.fr/pub/xpm">ftp://koala.inria.fr/pub/xpm</a>
  62
  63
  64 <h2><a name="sec3">3. Documentation</a></h2>
  65 <p>
  66 Old users might read the <a href="CHANGES">CHANGES</a> file for a history
  67 of changes interesting the user.
  68 <p>
  69 Read the doc. The documentation is in PostScript format (<a
  70 href="doc/xpm.PS">doc/xpm.PS</a>) and has been produced with
  71 FrameMaker. The source files are available on request.
  72 <p>
  73 A <a href="FAQ.html">FAQ</a> (Frequently Asked Questions) is also provided,
  74 so if you experience any problem you should have a look at this file.
  75
  76
  77 <h2><a name="sec4">4. Installation</a></h2>
  78 <p>
  79 To obtain the XPM library, first uncompress and untar the compressed tar file
  80 in an appropriate directory.
  81 <p>
  82 Then you can either compile XPM via "imake" or in a stand-alone way.
  83
  84 <h3><a name="sec4.1">4.1. With imake</a></h3>
  85 <p>
  86         Imakefiles are provided to build both shared and unshared libraries.
  87         However, building a shared lib is very OS dependent and often requires
  88         specific files which are not available. Also config files are often not
  89         set correctly for this task. So if it fails you can avoid trying to
  90         build one and simply build the static library instead. In order to do
  91         so you should edit the top Imakefile to add -DSharedLibXpm=NO to the
  92         definition of IMAKE_DEFINES as described.
  93 <p>
  94         The compilation and installation of the library and the sxpm program
  95         should only require you to edit the top Imakefile. But you should do so
  96         in order to specify the locations where the various files should be
  97         installed and to set the DEFINES variable accordingly to your system.
  98 <p>
  99         On Solaris 2.* the compilation works only in the native svr4
 100         environment, avoid the bsd one or it won't compile. Especially you
 101         should be using /opt/SUNWspro/bin/cc and not /usr/ucb/cc.
 102         Also since the compiler is no longer part of the OS distribution a lot
 103         of people use gcc instead. This is fine, but be aware that the imake
 104         tool you get as part of the X Window System on a solaris box is
 105         configured for cc. Therefore the compilation using the generated
 106         Makefiles will not succeed unless you have changed the default
 107         configuration. An easy work around is to directly edit the generated
 108         lib/Makefile to change '-K pic' to '-fpic'. Fixing your imake
 109         configuration would be better though.
 110 <p>
 111         On Linux, if you do not use ELF yet you'd better get the binary
 112         distribution available from sunsite. Because it's really a pain to
 113         build a shared lib and the current XPM distribution doesn't contain
 114         the jump files you would need to do so. On the other hand people have
 115         had no problems building it using ELF.
 116 <p>
 117         Then execute the following command:
 118 <pre>
 119                 xmkmf -a
 120 </pre>
 121 <p>
 122         or if this option is not supported by your version of xmkmf:
 123 <pre>
 124                 xmkmf
 125                 make Makefiles
 126                 make includes
 127                 make depend             (optional)
 128 </pre>
 129 <p>
 130         Then simply execute:
 131 <pre>
 132                 make
 133 </pre>
 134 <p>
 135         which will build the XPM library and the sxpm application.
 136         Then do:
 137 <pre>
 138                 make install
 139                 make install.man
 140 </pre>
 141 <p>
 142         which will install the library and the sxpm program and man page.
 143 <p>
 144         If it fails, be sure you have set the DEFINES correctly in the top
 145         Imakefile to suit your machine.
 146
 147 <h4>NOTE ON USING IMAKE:</h4>
 148 <p>
 149         Building the XPM distribution with imake requires to have imake
 150         <strong>correctly installed and configured</strong> on your
 151         system. I do my best at tweaking the Imakefiles so they work with
 152         as many imake flavors people might have as possible but there is
 153         nothing I can do against wrong imake configurations. So if your
 154         build fails using imake, don't send me email for advice. Get your
 155         imake configuration fixed or forget about it!
 156
 157
 158 <h3><a name="sec4.2">4.2. Without imake</a></h3>
 159 <p>
 160         A set of makefiles is provided for those who do not have imake
 161         available on their system. However, this is only provided as a
 162         convenience and you should be considered as a starting point and not as
 163         something ready to use. These makefiles, called Makefile.noX, will most
 164         likely require some editing in order be set accordingly to your system.
 165 <p>
 166         Once this setting is done, you should be able to compile XPM, by
 167         executing the following command:
 168 <pre>
 169                 make -f Makefile.noX
 170 </pre>
 171 <p>
 172         Then to install it, do:
 173 <pre>
 174                 make -f Makefile.noX install
 175 </pre>
 176
 177
 178 <h2><a name="sec5">5. SXPM</a></h2>
 179 <p>
 180 In addition to the library the sxpm tool is provided to show XPM file and
 181 convert them from XPM1 or XPM2 to XPM version 3. If you have previously done
 182 'make' or 'make all' you should already have it, otherwise just do:
 183 <pre>
 184                       cd sxpm; make
 185 </pre>
 186 <p>
 187 This application shows you most of the features of XPM and its source can be
 188 used to quickly see how to use the provided functions.
 189 <p>
 190 By executing 'sxpm -help' you will get the usage.
 191 <p>
 192 Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
 193 function. The pixmap is created from the static variable plaid defined in the
 194 sxpm.c file. sxpm will end when you press the key 'q' in the created window.
 195 <p>
 196 Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
 197 overriding color symbols giving a colorname, executing 'sxpm -plaid -sp
 198 lines_in_mix 1' will show overriding giving a pixel value, and executing 'sxpm
 199 -plaid -cp red 0' will show overriding giving a color value.
 200 <p>
 201 Then you should try 'sxpm -plaid -o output' to get an output file using the
 202 XpmWriteFileFromPixmap function.
 203 <p>
 204 You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
 205 get the pixmap printed out on the standard output with colornames instead of
 206 rgb values.
 207 <p>
 208 Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
 209 and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
 210 <p>
 211 The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
 212 flag to show the utility of this one. Indeed, compare the color section of the
 213 two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
 214 plaid.xpm -o bar'. All the default colors and also the comments have been
 215 restored.
 216 <p>
 217 To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
 218 extensions are handled.
 219 <p>
 220 Of course, other combinations are allowed and should be tried. Thus, 'sxpm
 221 plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
 222 to a XPM version 3 using sxpm.
 223 <p>
 224 See the manual page for more detail.
 225
 226
 227 <h2><a name="sec6">6. CXPM</a></h2>
 228 <p>
 229 The cxpm tool is provided to help you figure out whether an XPM file is correct
 230 or not with regard to its format. If you have previously done 'make' or
 231 'make all' you should already have it, otherwise just do:
 232 <pre>
 233                       cd cxpm; make
 234 </pre>
 235 <p>
 236 The related man page will tell you everything about it but here is a simple
 237 example of what it does:
 238 <pre>
 239 $ ./cxpm bogus_pixmap
 240 Xpm Error: Invalid XPM file.
 241 Error found line 3 near character 5
 242 </pre>
 243 <p>
 244 It is pretty limited but at least, unlike sxpm, it gives you some hint on where
 245 the error occured within the file.
 246
 247
 248 <h2><a name="sec7">7. Other Tools</a></h2>
 249 <p>
 250 Several converters dealing with XPM and a pixmap editor can be found in the
 251 xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
 252 general image operations such as scaling, resizing, dithering, and to convert
 253 from and to any other image format.
 254
 255 <h2><a name="sec8">8. Discussion</a></h2>
 256 <p>
 257 There is a mailing list to discuss about XPM which is <a
 258 href="mailto:xpm-talk@sophia.inria.fr">xpm-talk@sophia.inria.fr</a>.
 259 Any request to subscribe should be sent to <a
 260 href="mailto:xpm-talk-request@sophia.inria.fr">xpm-talk-request@sophia.inria.fr</a>.
 261 The archive of the xpm-talk list is available through the web at
 262 <a
 263 href="http://zenon.inria.fr/koala/xpm-talk-hypermail">http://zenon.inria.fr/koala/xpm-talk-hypermail</a>
 264 and through ftp at <a
 265 href="ftp://koala.inria.fr/pub/xpm/xpm-talk-archive">ftp://koala.inria.fr/pub/xpm/xpm-talk-archive</a>
 266 <p>
 267 Please mail any bug reports or modifications done, comments, suggestions,
 268 requests for updates or patches to port on another machine to:
 269
 270 <p>Email: <a href="lehors@sophia.inria.fr">lehors@sophia.inria.fr</a>
 271 <br>Phone: +33 (0)4 93 65 78 89
 272 <br>Surface Mail:<br>
 273 Arnaud Le Hors<br>
 274 Inria BP.93<br>
 275 2004, Route des lucioles<br>
 276 06902 Sophia Antipolis Cedex<br>
 277 FRANCE
 278
 279
 280 <hr>
 281 <h2><a name="copy">Copyright (C) 1989-95 GROUPE BULL</a></h2>
 282 <p>
 283 Permission is hereby granted, free of charge, to any person obtaining a copy
 284 of this software and associated documentation files (the "Software"), to
 285 deal in the Software without restriction, including without limitation the
 286 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 287 sell copies of the Software, and to permit persons to whom the Software is
 288 furnished to do so, subject to the following conditions:
 289 <p>
 290 The above copyright notice and this permission notice shall be included in
 291 all copies or substantial portions of the Software.
 292 <p>
 293 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 294 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 295 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 296 GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
 297 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 298 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 299 <p>
 300 Except as contained in this notice, the name of GROUPE BULL shall not be
 301 used in advertising or otherwise to promote the sale, use or other dealings
 302 in this Software without prior written authorization from GROUPE BULL.
 303 </body>