src/xpm/readme

   1 /*
   2  * Copyright (C) 1989-94 GROUPE BULL
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a copy
   5  * of this software and associated documentation files (the "Software"), to
   6  * deal in the Software without restriction, including without limitation the
   7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
   8  * sell copies of the Software, and to permit persons to whom the Software is
   9  * furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be included in
  12  * all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  17  * GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  18  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20  *
  21  * Except as contained in this notice, the name of GROUPE BULL shall not be
  22  * used in advertising or otherwise to promote the sale, use or other dealings
  23  * in this Software without prior written authorization from GROUPE BULL.
  24  */
  25
  26
  27                                 XPM Version 3
  28
  29 WHAT IS XPM?
  30 ============
  31
  32 XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
  33
  34 Here is provided a library containing a set of four functions, similar to the
  35 X bitmap functions as defined in the Xlib: XpmCreatePixmapFromData,
  36 XpmCreateDataFromPixmap, XpmReadFileToPixmap and XpmWriteFileFromPixmap for
  37 respectively including, storing, reading and writing this format, plus four
  38 other: XpmCreateImageFromData, XpmCreateDataFromImage, XpmReadFileToImage and
  39 XpmWriteFileFromImage for working with images instead of pixmaps.
  40
  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
  49 See the XPM Manual for more details.
  50
  51 HOW TO GET XPM?
  52 ===============
  53
  54 New xpm updates are announced on the comp.windows.x newsgroup, and on the
  55 "xpm-talk" list. All new "official" xpm releases can be found by ftp on:
  56
  57     ftp.x.org          (18.112.44.100) contrib   (Boston, USA)
  58     avahi.inria.fr     (192.5.60.47) pub         (Sophia Antipolis, France)
  59
  60
  61 DOCUMENTATION:
  62 =============
  63
  64 Old users might read the CHANGES file for a history of changes interesting
  65 the user.
  66
  67 Read the doc. The documentation is in PostScript format (file doc/xpm.ps) and
  68 has been produced with FrameMaker. The source files are available on request.
  69
  70
  71 INSTALLATION:
  72 ============
  73
  74 To obtain the XPM library, first uncompress and untar the compressed tar file
  75 in an approriate directory.
  76
  77 Then you can either compile xpm via "imake" or in a stand-alone way.
  78
  79 WITH IMAKE:
  80
  81         Imakefiles are provided to build both shared and unshared libraries.
  82         First have a look at the beginning of the lib/Imakefile and see if you
  83         need to do some modification to fit with your system.
  84         You should know how to use imake to build the XPM Makefiles
  85         by executing "xmkmf", then do:
  86
  87                 make Makefiles
  88                 make depend             (if you want to)
  89                 make
  90
  91         which will build the XPM library and the sxpm application.
  92         Then do:
  93
  94                 make install
  95                 make install.man
  96
  97         which will install the library and the sxpm pregram and man page.
  98
  99         If it fails, you may edit the Imakefiles to add compilation flags to
 100         suit your machine.
 101
 102 WITHOUT IMAKE:
 103
 104         To compile xpm, in the xpm directory you just created, do:
 105
 106                 make -f Makefile.noXtree
 107
 108         Then to install it, do:
 109
 110                 make -f Makefile.noXtree install
 111
 112 SXPM:
 113 ====
 114
 115 In addition to the library the sxpm tool is provided to show XPM file and
 116 convert them from XPM1 or XPM2 to XPM version 3. If you have previously done
 117 'make' or 'make all' you should have it yet, otherwise just do:
 118
 119                       cd sxpm; make
 120
 121 This application shows you most of the features of XPM and its source can be
 122 used to quickly see how to use the provided functions.
 123
 124 By executing 'sxpm -help' you will get the usage.
 125
 126 Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
 127 function. The pixmap is created from the static variable plaid defined in the
 128 sxpm.c file. sxpm will end when you press the key 'q' in the created window.
 129
 130 Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
 131 overriding color symbols giving a colorname, executing 'sxpm -sp lines_in_mix
 132 1' will show overriding giving a pixel value, and executing 'sxpm -plaid -cp
 133 red 0' will show overriding giving a color value.
 134
 135 Then you should try 'sxpm -plaid -o output' to get an output file using the
 136 XpmWriteFileFromPixmap function.
 137
 138 You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
 139 get the pixmap printed out on the standard output with colornames instead of
 140 rgb values.
 141
 142 Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
 143 and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
 144
 145 The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
 146 flag to show the utility of this one. Indeed, compare the color section of the
 147 two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
 148 plaid.xpm -o bar'. All the default colors and also the comments have been
 149 restored.
 150
 151 To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
 152 extensions are handled.
 153
 154 Of course, other combinations are allowed and should be tried. Thus, 'sxpm
 155 plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
 156 to a XPM version 3 using sxpm.
 157
 158 See the manual page for more detail.
 159
 160 OTHER TOOLS:
 161 ===========
 162
 163 Several converters dealing with XPM and a pixmap editor can be found in the
 164 xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
 165 general image operations such as scaling, resizing, dithering, and to convert
 166 from and to any other image format.
 167
 168 DISCUSSION:
 169 ==========
 170
 171 There is a mailing list to discuss about XPM which is xpm-talk@sophia.inria.fr.
 172 Any request to subscribe should be sent to xpm-talk-request@sophia.inria.fr.
 173
 174 COPYRIGHT:
 175 ==========
 176
 177   Copyright 1989-94 GROUPE BULL --
 178   See license conditions in the COPYRIGHT file of the XPM distribution
 179
 180 Please mail any bug reports or modifications done, comments, suggestions,
 181 requests for updates or patches to port on another machine to:
 182
 183 lehors@sophia.inria.fr          (INTERNET)
 184
 185 33 (FRANCE) 93.65.77.71         (VOICE PHONE)
 186
 187 Arnaud Le Hors                  (SURFACE MAIL)
 188 Bull c/o Inria BP. 109
 189 2004, Route des lucioles
 190 Sophia Antipolis
 191 06561 Valbonne Cedex
 192 FRANCE