← Back to branch summary

~ubuntu-branches/ubuntu/intrepid/plplot/intrepid

« back to all changes in this revision

Viewing changes to doc/docbook/src/api.xml

  • Committer: Bazaar Package Importer
  • Author(s): Rafael Laboissiere
  • Date: 2006-11-04 10:19:34 UTC
  • mfrom: (2.1.8 edgy)
  • Revision ID: james.westby@ubuntu.com-20061104101934-mlirvdg4gpwi6i5q
Tags: 5.6.1-10
* Orphaning the package
* debian/control: Changed the maintainer to the Debian QA Group

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/docbook/src/api.xml
41
41
  <para>
42
42
  The purpose of this chapter is to document the API for every C function in
43
43
  PLplot that should have a counterpart in other PLplot language bindings such as
44
 
  Fortran.  These common API routines have a special
 
44
  Fortran 77.  These common API routines have a special
45
45
  <quote>c_</quote> prefix name assigned to them in <filename>plplot.h</filename>.
46
46
  This common API between the various languages constitutes the
47
47
  most important part of the PLplot API that programmers need to know.
51
51
 
52
52
  <para>
53
53
All common API functions of the current CVS HEAD are listed here with their
54
 
arguments.  All functions (other than the deprecated ones)
55
 
have at a short description, and all parameters are documented.
 
54
arguments except for obsolete/deprecated API which is listed in <xref
 
55
linkend="API-OBSOLETE"/>.
 
56
All functions have a short description, and all parameters are documented.
56
57
  </para>
57
58
 
58
59
  <sect1 id="pl_setcontlabelformat" renderas="sect3">
197
198
      Advances to the next subpage if
198
199
      <literal><parameter>sub</parameter>=0</literal>, performing a page
199
200
      advance if there are no remaining subpages on the current page.  If
200
 
      subwindowing isn't being used, <literal>&pladv;(0)</literal> will
 
201
      subpages aren't being used, <literal>&pladv;(0)</literal> will
201
202
      always advance the page.  If
202
203
      <literal><parameter>sub</parameter>&gt;0</literal>, PLplot switches
203
204
      to the specified subpage.  Note that this allows you to overwrite a
474
475
        <paramdef><parameter>nbin</parameter></paramdef>
475
476
        <paramdef><parameter>x</parameter></paramdef>
476
477
        <paramdef><parameter>y</parameter></paramdef>
477
 
        <paramdef><parameter>center</parameter></paramdef>
 
478
        <paramdef><parameter>opt</parameter></paramdef>
478
479
      </funcprototype>
479
480
      </funcsynopsis>
480
481
    </para>
488
489
      <literal><parameter>y</parameter>[i]</literal>.  For proper
489
490
      operation, the values in
490
491
      <literal><parameter>x</parameter>[i]</literal> must form a strictly
491
 
      increasing sequence.  If
492
 
      <literal><parameter>center</parameter>=0</literal>,
 
492
      increasing sequence.  By default,
493
493
      <literal><parameter>x</parameter>[i]</literal> is the left-hand edge
494
 
      of the <literal>i</literal>'th bin, and if
495
 
      <literal><parameter>center</parameter>=1</literal>, the bin
496
 
      boundaries are placed midway between the values in the
 
494
      of the <literal>i</literal>'th bin. If
 
495
      <literal><parameter>opt</parameter>=PL_BIN_CENTRED</literal> is
 
496
      used, the bin boundaries are placed midway between the values in the
497
497
      <literal><parameter>x</parameter></literal> array.  Also see &plhist;
498
498
      for drawing histograms from unbinned data.
499
499
    </para>
539
539
      </varlistentry>
540
540
      <varlistentry>
541
541
        <term>
542
 
          <parameter>center</parameter>
 
542
          <parameter>opt</parameter>
543
543
          (<literal>PLINT</literal>, input)
544
544
        </term>
545
545
        <listitem>
546
546
          <para>
547
 
            Indicates whether the values in
548
 
            <literal><parameter>x</parameter></literal> represent the lower
549
 
            bin boundaries
550
 
            (<literal><parameter>center</parameter>=0</literal>) or whether
551
 
            the bin boundaries are to be midway between the
552
 
            <literal><parameter>x</parameter></literal> values
553
 
            (<literal><parameter>center</parameter>=1</literal>).  If the
554
 
            values in <literal><parameter>x</parameter></literal> are
555
 
            equally spaced and
556
 
            <literal><parameter>center</parameter>=1</literal>, the values
557
 
            in <literal><parameter>x</parameter></literal> are the center
558
 
            values of the bins.
 
547
            Is a combination of several flags:
 
548
            <itemizedlist>
 
549
              <listitem>
 
550
                <para>
 
551
                  <literal><parameter>opt</parameter>=PL_BIN_DEFAULT</literal>:
 
552
                    The <literal><parameter>x</parameter></literal> represent the lower
 
553
                    bin boundaries, the outer bins are expanded to fill up the
 
554
                    entire x-axis and bins of zero height are simply drawn.
 
555
                </para>
 
556
              </listitem>
 
557
              <listitem>
 
558
                <para>
 
559
                  <literal><parameter>opt</parameter>=PL_BIN_CENTRED|...</literal>:
 
560
                    The bin boundaries are to be midway between the
 
561
                    <literal><parameter>x</parameter></literal> values. If the
 
562
                    values in <literal><parameter>x</parameter></literal> are
 
563
                    equally spaced, the values are the center values of the bins.
 
564
                </para>
 
565
              </listitem>
 
566
              <listitem>
 
567
                <para>
 
568
                  <literal><parameter>opt</parameter>=PL_BIN_NOEXPAND|...</literal>:
 
569
                    The outer bins are drawn with equal size as the ones inside.
 
570
                </para>
 
571
              </listitem>
 
572
              <listitem>
 
573
                <para>
 
574
                  <literal><parameter>opt</parameter>=PL_BIN_NOEMPTY|...</literal>:
 
575
                    Bins with zero height are not drawn (there is a gap for
 
576
                    such bins).
 
577
                </para>
 
578
              </listitem>
 
579
            </itemizedlist>
559
580
          </para>
560
581
        </listitem>
561
582
      </varlistentry>
581
602
      necessary.  Advancing the page via &pleop; and &plbop; is useful when
582
603
      a page break is desired at a particular point when plotting to
583
604
      subpages.  Another use for &pleop; and &plbop; is when plotting pages
584
 
      to different files, since you can manually set the file name (or file
585
 
      handle) by calling &plsfnam; or &plsfile; after the call to &pleop;
586
 
      (in fact some drivers may only support a single page per file, making
587
 
      this a necessity).  One way to handle this case automatically is to
 
605
      to different files, since you can manually set the file name
 
606
      by calling &plsfnam; after the call to &pleop;.
 
607
      (In fact some drivers may only support a single page per file, making
 
608
      this a necessity.)  One way to handle this case automatically is to
588
609
      page advance via &pladv;, but enable familying (see &plsfam;) with a
589
610
      small limit on the file size so that a new family member file will be
590
611
      created on each page break.
1265
1286
 
1266
1287
  </sect1>
1267
1288
 
1268
 
  <sect1 id="plclr" renderas="sect3">
1269
 
    <title>
1270
 
      <function>plclr</function>: Eject current page
1271
 
    </title>
1272
 
 
1273
 
    <para>
1274
 
      <funcsynopsis>
1275
 
      <funcprototype>
1276
 
        <funcdef>
1277
 
          <function>plclr</function>
1278
 
        </funcdef>
1279
 
        <paramdef></paramdef>
1280
 
      </funcprototype>
1281
 
      </funcsynopsis>
1282
 
    </para>
1283
 
 
1284
 
    <para>
1285
 
      Deprecated.  Use the new name, &pleop;, for this function instead.
1286
 
    </para>
1287
 
 
1288
 
  </sect1>
1289
 
 
1290
 
  <sect1 id="plcol" renderas="sect3">
1291
 
    <title>
1292
 
      <function>plcol</function>: Set color
1293
 
    </title>
1294
 
 
1295
 
    <para>
1296
 
      <funcsynopsis>
1297
 
      <funcprototype>
1298
 
        <funcdef>
1299
 
          <function>plcol</function>
1300
 
        </funcdef>
1301
 
        <paramdef><parameter>color</parameter></paramdef>
1302
 
      </funcprototype>
1303
 
      </funcsynopsis>
1304
 
    </para>
1305
 
 
1306
 
    <para>
1307
 
      Deprecated.  Use the new name, &plcol0;, for this function instead.
1308
 
    </para>
1309
 
 
1310
 
    <variablelist>
1311
 
      <varlistentry>
1312
 
        <term>
1313
 
          <parameter>color</parameter>
1314
 
          (<literal>PLINT</literal>, input)
1315
 
        </term>
1316
 
        <listitem>
1317
 
          <para>
1318
 
            See &plcol0;.
1319
 
          </para>
1320
 
        </listitem>
1321
 
      </varlistentry>
1322
 
    </variablelist>
1323
 
 
1324
 
 
1325
 
  </sect1>
1326
 
 
1327
1289
  <sect1 id="plcol0" renderas="sect3">
1328
1290
    <title>
1329
1291
      <function>plcol0</function>: Set color, map0
1354
1316
          <para>
1355
1317
            Integer representing the color.  The defaults at present are
1356
1318
            (these may change):
1357
 
            <simplelist type="vert" columns="2">
1358
 
              <member> 0 </member>
1359
 
              <member> 1 </member>
1360
 
              <member> 2 </member>
1361
 
              <member> 3 </member>
1362
 
              <member> 4 </member>
1363
 
              <member> 5 </member>
1364
 
              <member> 6 </member>
1365
 
              <member> 7 </member>
1366
 
              <member> 8 </member>
1367
 
              <member> 9 </member>
1368
 
              <member>10 </member>
1369
 
              <member>11 </member>
1370
 
              <member>12 </member>
1371
 
              <member>13 </member>
1372
 
              <member>14 </member>
1373
 
              <member>15 </member>
1374
 
              <member>black (default background)</member>
1375
 
              <member>red (default foreground)</member>
1376
 
              <member>yellow</member>
1377
 
              <member>green</member>
1378
 
              <member>aquamarine</member>
1379
 
              <member>pink</member>
1380
 
              <member>wheat</member>
1381
 
              <member>grey</member>
1382
 
              <member>brown</member>
1383
 
              <member>blue</member>
1384
 
              <member>BlueViolet</member>
1385
 
              <member>cyan</member>
1386
 
              <member>turquoise</member>
1387
 
              <member>magenta</member>
1388
 
              <member>salmon</member>
1389
 
              <member>white</member>
 
1319
            <simplelist type="horiz" columns="2">
 
1320
              <member> 0 </member>  <member>black (default background)</member>
 
1321
              <member> 1 </member>  <member>red (default foreground)</member>
 
1322
              <member> 2 </member>  <member>yellow</member>
 
1323
              <member> 3 </member>  <member>green</member>
 
1324
              <member> 4 </member>  <member>aquamarine</member>
 
1325
              <member> 5 </member>  <member>pink</member>
 
1326
              <member> 6 </member>  <member>wheat</member>
 
1327
              <member> 7 </member>  <member>grey</member>
 
1328
              <member> 8 </member>  <member>brown</member>
 
1329
              <member> 9 </member>  <member>blue</member>
 
1330
              <member>10 </member>  <member>BlueViolet</member>
 
1331
              <member>11 </member>  <member>cyan</member>
 
1332
              <member>12 </member>  <member>turquoise</member>
 
1333
              <member>13 </member>  <member>magenta</member>
 
1334
              <member>14 </member>  <member>salmon</member>
 
1335
              <member>15 </member>  <member>white</member>
1390
1336
            </simplelist>
1391
1337
            Use &plscmap0; to change the entire map0 color palette and
1392
1338
            &plscol0; to change an individual color in the map0 color
1639
1585
      <varlistentry>
1640
1586
        <term>
1641
1587
          <parameter>flags</parameter>
1642
 
          (<literal>PLINT</literal>, input)
 
1588
          (<literal>PLBOOL</literal>, input)
1643
1589
        </term>
1644
1590
        <listitem>
1645
1591
          <para>
1646
 
            If <literal><parameter>flags</parameter></literal> is set to 1
 
1592
            If <literal><parameter>flags</parameter></literal> is set to true
1647
1593
            the device coordinates are <emphasis>not</emphasis> copied from the reference to current
1648
1594
            stream.
1649
1595
          </para>
3223
3169
    </variablelist>
3224
3170
 
3225
3171
  </sect1>
 
3172
  <sect1 id="plgfci" renderas="sect3">
 
3173
    <title>
 
3174
      <function>plgfci</function>: Get FCI (font characterization integer)
 
3175
    </title>
 
3176
 
 
3177
    <para>
 
3178
      <funcsynopsis>
 
3179
      <funcprototype>
 
3180
        <funcdef>
 
3181
          <function>plgfci</function>
 
3182
        </funcdef>
 
3183
        <paramdef><parameter>fci</parameter></paramdef>
 
3184
      </funcprototype>
 
3185
      </funcsynopsis>
 
3186
    </para>
 
3187
 
 
3188
    <para>
 
3189
      Gets information about the current font using the FCI approach.
 
3190
      See <xref linkend="fci"/> for more information.
 
3191
    </para>
 
3192
 
 
3193
    <variablelist>
 
3194
      <varlistentry>
 
3195
        <term>
 
3196
          <parameter>fci</parameter>
 
3197
          (<literal>PLUNICODE *</literal>, output)
 
3198
        </term>
 
3199
        <listitem>
 
3200
          <para>
 
3201
            Pointer to PLUNICODE (unsigned 32-bit integer) variable which
 
3202
            is updated with current FCI value.
 
3203
          </para>
 
3204
        </listitem>
 
3205
      </varlistentry>
 
3206
    </variablelist>
 
3207
 
 
3208
  </sect1>
3226
3209
 
3227
3210
  <sect1 id="plgfnam" renderas="sect3">
3228
3211
    <title>
4168
4151
        <paramdef><parameter>datmin</parameter></paramdef>
4169
4152
        <paramdef><parameter>datmax</parameter></paramdef>
4170
4153
        <paramdef><parameter>nbin</parameter></paramdef>
4171
 
        <paramdef><parameter>oldwin</parameter></paramdef>
 
4154
        <paramdef><parameter>opt</parameter></paramdef>
4172
4155
      </funcprototype>
4173
4156
      </funcsynopsis>
4174
4157
    </para>
4182
4165
      <literal><parameter>datmin</parameter></literal> and
4183
4166
      <literal><parameter>datmax</parameter></literal>, and calls &plbin;
4184
4167
      to draw the resulting histogram.  Parameter
4185
 
      <literal><parameter>oldwin</parameter></literal> allows the histogram
4186
 
      either to be plotted in an existing window or causes &plhist; to call
4187
 
      &plenv; with suitable limits before plotting the histogram.
 
4168
      <literal><parameter>opt</parameter></literal> allows, among
 
4169
      other things, the histogram either to be plotted in an existing window
 
4170
      or causes &plhist; to call &plenv; with suitable limits before plotting
 
4171
      the histogram.
4188
4172
    </para>
4189
4173
 
4190
4174
    <variablelist>
4248
4232
      </varlistentry>
4249
4233
      <varlistentry>
4250
4234
        <term>
4251
 
          <parameter>oldwin</parameter>
 
4235
          <parameter>opt</parameter>
4252
4236
          (<literal>PLINT</literal>, input)
4253
4237
        </term>
4254
4238
        <listitem>
4255
4239
          <para>
4256
 
            If one, the histogram is plotted in the currently-defined
4257
 
            window, and if zero, &plenv; is called automatically before
4258
 
            plotting.
4259
 
          </para>
4260
 
        </listitem>
4261
 
      </varlistentry>
4262
 
    </variablelist>
4263
 
 
4264
 
  </sect1>
4265
 
 
4266
 
  <sect1 id="plhls" renderas="sect3">
4267
 
    <title>
4268
 
      <function>plhls</function>: Set current color by HLS
4269
 
    </title>
4270
 
 
4271
 
    <para>
4272
 
      <funcsynopsis>
4273
 
      <funcprototype>
4274
 
        <funcdef>
4275
 
           <function>plhls</function>
4276
 
        </funcdef>
4277
 
        <paramdef><parameter>h</parameter></paramdef>
4278
 
        <paramdef><parameter>l</parameter></paramdef>
4279
 
        <paramdef><parameter>s</parameter></paramdef>
4280
 
      </funcprototype>
4281
 
      </funcsynopsis>
4282
 
    </para>
4283
 
 
4284
 
    <para>
4285
 
      Set current color by hue, lightness, and saturation.
4286
 
      Convert hls color coordinates to rgb, then call plrgb.
4287
 
      Do <emphasis>not</emphasis> use this.  Only retained for backward compatibility.
4288
 
      Use plHLS_RGB and plscol0 instead.
4289
 
    </para>
4290
 
<!-- TODO: find out what to do exactly -->
4291
 
 
4292
 
    <variablelist>
4293
 
      <varlistentry>
4294
 
        <term>
4295
 
          <parameter>h</parameter>
4296
 
          (<literal>PLFLT</literal>, input)
4297
 
        </term>
4298
 
        <listitem>
4299
 
          <para>
4300
 
            NEEDS DOCUMENTATION
4301
 
          </para>
4302
 
        </listitem>
4303
 
      </varlistentry>
4304
 
      <varlistentry>
4305
 
        <term>
4306
 
          <parameter>l</parameter>
4307
 
          (<literal>PLFLT</literal>, input)
4308
 
        </term>
4309
 
        <listitem>
4310
 
          <para>
4311
 
            NEEDS DOCUMENTATION
4312
 
          </para>
4313
 
        </listitem>
4314
 
      </varlistentry>
4315
 
      <varlistentry>
4316
 
        <term>
4317
 
          <parameter>s</parameter>
4318
 
          (<literal>PLFLT</literal>, input)
4319
 
        </term>
4320
 
        <listitem>
4321
 
          <para>
4322
 
            NEEDS DOCUMENTATION
4323
 
          </para>
4324
 
        </listitem>
4325
 
      </varlistentry>
4326
 
    </variablelist>
4327
 
 
4328
 
  </sect1>
4329
 
 
4330
 
  <sect1 id="plHLS_RGB" renderas="sect3">
4331
 
    <title>
4332
 
      <function>plHLS_RGB</function>: Convert HLS color to RGB
4333
 
    </title>
4334
 
 
4335
 
    <para>
4336
 
      <funcsynopsis>
4337
 
      <funcprototype>
4338
 
        <funcdef>
4339
 
           <function>plHLS_RGB</function>
 
4240
            Is a combination of several flags:
 
4241
            <itemizedlist>
 
4242
              <listitem>
 
4243
                <para>
 
4244
                  <literal><parameter>opt</parameter>=PL_HIST_DEFAULT</literal>:
 
4245
                    The axes are automatically rescaled to fit the histogram data,
 
4246
                    the outer bins are expanded to fill up the entire x-axis,
 
4247
                    data outside the given extremes are assigned to the outer
 
4248
                    bins and bins of zero height are simply drawn.
 
4249
                </para>
 
4250
              </listitem>
 
4251
              <listitem>
 
4252
                <para>
 
4253
                  <literal><parameter>opt</parameter>=PL_HIST_NOSCALING|...</literal>:
 
4254
                    The existing axes are not rescaled to fit the histogram data,
 
4255
                    without this flag, &plenv; is called to set the world coordinates.
 
4256
                </para>
 
4257
              </listitem>
 
4258
              <listitem>
 
4259
                <para>
 
4260
                  <literal><parameter>opt</parameter>=PL_HIST_IGNORE_OUTLIERS|...</literal>:
 
4261
                    Data outside the given extremes are not taken into account.
 
4262
                    This option should probably be combined with
 
4263
                    <literal><parameter>opt</parameter>=PL_HIST_NOEXPAND|...</literal>,
 
4264
                    so as to properly present the data.
 
4265
                </para>
 
4266
              </listitem>
 
4267
              <listitem>
 
4268
                <para>
 
4269
                  <literal><parameter>opt</parameter>=PL_HIST_NOEXPAND|...</literal>:
 
4270
                    The outer bins are drawn with equal size as the ones inside.
 
4271
                </para>
 
4272
              </listitem>
 
4273
              <listitem>
 
4274
                <para>
 
4275
                  <literal><parameter>opt</parameter>=PL_HIST_NOEMPTY|...</literal>:
 
4276
                    Bins with zero height are not drawn (there is a gap for
 
4277
                    such bins).
 
4278
                </para>
 
4279
              </listitem>
 
4280
            </itemizedlist>
 
4281
          </para>
 
4282
        </listitem>
 
4283
      </varlistentry>
 
4284
    </variablelist>
 
4285
 
 
4286
  </sect1>
 
4287
 
 
4288
  <sect1 id="plhlsrgb" renderas="sect3">
 
4289
    <title>
 
4290
      <function>plhlsrgb</function>: Convert HLS color to RGB
 
4291
    </title>
 
4292
 
 
4293
    <para>
 
4294
      <funcsynopsis>
 
4295
      <funcprototype>
 
4296
        <funcdef>
 
4297
           <function>plhlsrgb</function>
4340
4298
        </funcdef>
4341
4299
        <paramdef><parameter>h</parameter></paramdef>
4342
4300
        <paramdef><parameter>l</parameter></paramdef>
4349
4307
    </para>
4350
4308
 
4351
4309
    <para>
4352
 
      Convert hls color coordinates to rgb
 
4310
      Convert HLS color coordinates to RGB
4353
4311
    </para>
4354
4312
 
4355
4313
    <variablelist>
4450
4408
      or the &plsdev; function), or if only one device is
4451
4409
      enabled when PLplot is installed.  If subpages have been specified,
4452
4410
      the output device is divided into <literal>nx</literal> by
4453
 
      <literal>ny</literal> sub-pages, each of which may be used
 
4411
      <literal>ny</literal> subpages, each of which may be used
4454
4412
      independently.  If &plinit; is called again during a program, the
4455
4413
      previously opened file will be closed.  The subroutine &pladv; is
4456
4414
      used to advance from one subpage to the next.
4837
4795
 
4838
4796
  </sect1>
4839
4797
 
 
4798
  <sect1 id="plmap" renderas="sect3">
 
4799
    <title>
 
4800
      <function>plmap</function>: Plot continental outline in world coordinates.
 
4801
    </title>
 
4802
 
 
4803
    <para>
 
4804
     <funcsynopsis>
 
4805
      <funcprototype>
 
4806
           <funcdef>
 
4807
            <function>plmap</function>
 
4808
           </funcdef>
 
4809
       <paramdef><parameter>mapform</parameter></paramdef>
 
4810
       <paramdef><parameter>type</parameter></paramdef>
 
4811
       <paramdef><parameter>minlong</parameter></paramdef>
 
4812
       <paramdef><parameter>maxlong</parameter></paramdef>
 
4813
       <paramdef><parameter>minlat</parameter></paramdef>
 
4814
       <paramdef><parameter>maxlat</parameter></paramdef>
 
4815
      </funcprototype>
 
4816
     </funcsynopsis>
 
4817
    </para>
 
4818
 
 
4819
    <para>
 
4820
      Plots continental outlines in world coordinates.
 
4821
      examples/c/x19c demonstrates how to use this 
 
4822
      function to create different projections.
 
4823
    </para>
 
4824
 
 
4825
    <variablelist>
 
4826
     <varlistentry>
 
4827
          <term>
 
4828
           <parameter>mapform</parameter>
 
4829
           (<literal>void (*) (PLINT, PLFLT *, PLFLT *)</literal>, input)
 
4830
          </term>
 
4831
          <listitem>
 
4832
           <para>
 
4833
      A user supplied function to transform the coordinate 
 
4834
      longitudes and latitudes to a plot coordinate system.  
 
4835
      By using this transform, we can change from a longitude, 
 
4836
      latitude coordinate to a polar stereographic project, for 
 
4837
      example.  Initially, x[0]..[n-1] are the longitudes and y[0]..y[n-1] 
 
4838
      are the corresponding latitudes.  After the call to mapform(), x[] 
 
4839
      and y[] should be replaced by the corresponding plot coordinates.  
 
4840
      If no transform is desired, mapform can be replaced by NULL.
 
4841
           </para>
 
4842
          </listitem>
 
4843
     </varlistentry>
 
4844
     <varlistentry>
 
4845
          <term>
 
4846
           <parameter>type</parameter>
 
4847
            (<literal>char *</literal>, input)
 
4848
          </term>
 
4849
          <listitem>
 
4850
           <para>
 
4851
      type is a character string. The value of this parameter determines the
 
4852
      type of background. The possible values are:
 
4853
        <itemizedlist>
 
4854
         <listitem>
 
4855
          <para>
 
4856
               <literal>"globe"</literal> -- continental outlines
 
4857
          </para>
 
4858
         </listitem>
 
4859
         <listitem>
 
4860
          <para>
 
4861
           <literal>"usa"</literal> -- USA and state boundaries
 
4862
          </para>
 
4863
         </listitem>
 
4864
         <listitem>
 
4865
          <para>
 
4866
           <literal>"cglobe"</literal> -- continental outlines and countries
 
4867
          </para>
 
4868
         </listitem>
 
4869
         <listitem>
 
4870
          <para>
 
4871
           <literal>"usaglobe"</literal> -- USA, state boundaries and continental outlines
 
4872
          </para>
 
4873
         </listitem>
 
4874
            </itemizedlist>
 
4875
           </para>
 
4876
          </listitem>
 
4877
     </varlistentry>
 
4878
     <varlistentry>
 
4879
          <term>
 
4880
           <parameter>minlong</parameter>
 
4881
           (<literal>PLFLT</literal>, input)
 
4882
          </term>
 
4883
          <listitem>
 
4884
           <para>
 
4885
      The value of the longitude on the left side of the plot. 
 
4886
      The value of minlong must be less than the value of maxlong, and the 
 
4887
      quantity maxlong-minlong must be less than or equal to 360.
 
4888
           </para>
 
4889
          </listitem>
 
4890
     </varlistentry>
 
4891
     <varlistentry>
 
4892
          <term>
 
4893
           <parameter>maxlong</parameter>
 
4894
           (<literal>PLFLT</literal>, input)
 
4895
          </term>
 
4896
          <listitem>
 
4897
           <para>
 
4898
       The value of the longitude on the right side of the plot.
 
4899
           </para>
 
4900
          </listitem>
 
4901
     </varlistentry>
 
4902
     <varlistentry>
 
4903
          <term>
 
4904
           <parameter>minlat</parameter>
 
4905
           (<literal>PLFLT</literal>, input)
 
4906
          </term>
 
4907
          <listitem>
 
4908
           <para>
 
4909
       The minimum latitude to be plotted on the background.  
 
4910
       One can always use -90.0 as the boundary outside the plot window 
 
4911
       will be automatically eliminated.  However, the program will be 
 
4912
       faster if one can reduce the size of the background plotted.
 
4913
           </para>
 
4914
          </listitem>
 
4915
     </varlistentry>
 
4916
     <varlistentry>
 
4917
          <term>
 
4918
           <parameter>maxlat</parameter>
 
4919
           (<literal>PLFLT</literal>, input)
 
4920
          </term>
 
4921
          <listitem>
 
4922
           <para>
 
4923
       The maximum latitudes to be plotted on the background.  
 
4924
       One can always use 90.0 as the boundary outside the plot window 
 
4925
       will be automatically eliminated.
 
4926
           </para>
 
4927
          </listitem>
 
4928
     </varlistentry>
 
4929
    </variablelist>
 
4930
  </sect1>
 
4931
 
 
4932
  <sect1 id="plmeridians" renderas="sect3">
 
4933
    <title>
 
4934
     <function>plmeridians</function>: Plot latitude and longitude lines.
 
4935
    </title>
 
4936
 
 
4937
    <para>
 
4938
     <funcsynopsis>
 
4939
      <funcprototype>
 
4940
           <funcdef>
 
4941
            <function>plmeridians</function>
 
4942
           </funcdef>
 
4943
       <paramdef><parameter>mapform</parameter></paramdef>
 
4944
       <paramdef><parameter>dlong</parameter></paramdef>
 
4945
       <paramdef><parameter>dlat</parameter></paramdef>
 
4946
       <paramdef><parameter>minlong</parameter></paramdef>
 
4947
       <paramdef><parameter>maxlong</parameter></paramdef>
 
4948
       <paramdef><parameter>minlat</parameter></paramdef>
 
4949
       <paramdef><parameter>maxlat</parameter></paramdef>
 
4950
      </funcprototype>
 
4951
     </funcsynopsis>
 
4952
    </para>
 
4953
 
 
4954
    <para>
 
4955
     Displays latitude and longitude on the current plot.  The lines
 
4956
     are plotted in the current color and line style.
 
4957
    </para>
 
4958
 
 
4959
    <variablelist>
 
4960
     <varlistentry>
 
4961
          <term>
 
4962
           <parameter>mapform</parameter>
 
4963
           (<literal>void (*) (PLINT, PLFLT *, PLFLT *)</literal>, input)
 
4964
          </term>
 
4965
          <listitem>
 
4966
           <para>
 
4967
      A user supplied function to transform the coordinate 
 
4968
      longitudes and latitudes to a plot coordinate system.  
 
4969
      By using this transform, we can change from a longitude, 
 
4970
      latitude coordinate to a polar stereographic project, for 
 
4971
      example.  Initially, x[0]..[n-1] are the longitudes and y[0]..y[n-1] 
 
4972
      are the corresponding latitudes.  After the call to mapform(), x[] 
 
4973
      and y[] should be replaced by the corresponding plot coordinates.  
 
4974
      If no transform is desired, mapform can be replaced by NULL.
 
4975
           </para>
 
4976
          </listitem>
 
4977
     </varlistentry>
 
4978
     <varlistentry>
 
4979
          <term>
 
4980
           <parameter>dlong</parameter>
 
4981
          (<literal>PLFLT</literal>, input)
 
4982
          </term>
 
4983
          <listitem>
 
4984
           <para>
 
4985
       The interval in degrees at which the longitude lines are to be plotted.
 
4986
           </para>
 
4987
          </listitem>
 
4988
     </varlistentry>
 
4989
     <varlistentry>
 
4990
          <term>
 
4991
           <parameter>dlat</parameter>
 
4992
          (<literal>PLFLT</literal>, input)
 
4993
          </term>
 
4994
          <listitem>
 
4995
           <para>
 
4996
       The interval in degrees at which the latitude lines are to be plotted.
 
4997
           </para>
 
4998
          </listitem>
 
4999
     </varlistentry>
 
5000
     <varlistentry>
 
5001
          <term>
 
5002
           <parameter>minlong</parameter>
 
5003
           (<literal>PLFLT</literal>, input)
 
5004
          </term>
 
5005
          <listitem>
 
5006
           <para>
 
5007
      The value of the longitude on the left side of the plot. 
 
5008
      The value of minlong must be less than the value of maxlong, and the 
 
5009
      quantity maxlong-minlong must be less than or equal to 360.
 
5010
           </para>
 
5011
          </listitem>
 
5012
     </varlistentry>
 
5013
     <varlistentry>
 
5014
          <term>
 
5015
           <parameter>maxlong</parameter>
 
5016
           (<literal>PLFLT</literal>, input)
 
5017
          </term>
 
5018
          <listitem>
 
5019
           <para>
 
5020
      The value of the longitude on the right side of the plot.
 
5021
           </para>
 
5022
          </listitem>
 
5023
     </varlistentry>
 
5024
     <varlistentry>
 
5025
          <term>
 
5026
           <parameter>minlat</parameter>
 
5027
          (<literal>PLFLT</literal>, input)
 
5028
          </term>
 
5029
          <listitem>
 
5030
           <para>
 
5031
      The minimum latitude to be plotted on the background.  
 
5032
      One can always use -90.0 as the boundary outside the plot window 
 
5033
      will be automatically eliminated.  However, the program will be 
 
5034
      faster if one can reduce the size of the background plotted.
 
5035
           </para>
 
5036
          </listitem>
 
5037
     </varlistentry>
 
5038
     <varlistentry>
 
5039
          <term>
 
5040
           <parameter>maxlat</parameter>
 
5041
           (<literal>PLFLT</literal>, input)
 
5042
          </term>
 
5043
          <listitem>
 
5044
           <para>
 
5045
      The maximum latitudes to be plotted on the background.  
 
5046
      One can always use 90.0 as the boundary outside the plot window 
 
5047
      will be automatically eliminated.
 
5048
           </para>
 
5049
          </listitem>
 
5050
     </varlistentry>
 
5051
    </variablelist>
 
5052
  </sect1>
 
5053
 
4840
5054
  <sect1 id="plmesh" renderas="sect3">
4841
5055
    <title>
4842
5056
      <function>plmesh</function>: Plot surface mesh
5493
5707
      <varlistentry>
5494
5708
        <term>
5495
5709
          <parameter>side</parameter>
5496
 
          (<literal>PLINT</literal>, input)
 
5710
          (<literal>PLBOOL</literal>, input)
5497
5711
        </term>
5498
5712
        <listitem>
5499
5713
          <para>
5500
5714
            Flag to indicate whether or not ``sides'' should be draw on the
5501
 
            figure.  If <literal><parameter>side</parameter>=0</literal> no
5502
 
            sides are drawn, otherwise the sides are drawn.
 
5715
            figure.  If <literal><parameter>side</parameter></literal> is true
 
5716
            sides are drawn, otherwise no sides are drawn.
5503
5717
          </para>
5504
5718
        </listitem>
5505
5719
      </varlistentry>
5543
5757
 
5544
5758
    </sect1>
5545
5759
 
5546
 
  <sect1 id="plpage" renderas="sect3">
 
5760
  <sect1 id="plparseopts" renderas="sect3">
5547
5761
    <title>
5548
 
      <function>plpage</function>: Begin a new page
 
5762
      <function>plparseopts</function>: Parse command-line arguments
5549
5763
    </title>
5550
5764
 
5551
5765
    <para>
5552
5766
      <funcsynopsis>
5553
5767
      <funcprototype>
5554
5768
        <funcdef>
5555
 
          <function>plpage</function>
 
5769
          <function>plparseopts</function>
5556
5770
        </funcdef>
5557
 
        <paramdef></paramdef>
 
5771
        <paramdef><parameter>p_argc</parameter></paramdef>
 
5772
        <paramdef><parameter>argv</parameter></paramdef>
 
5773
        <paramdef><parameter>mode</parameter></paramdef>
5558
5774
      </funcprototype>
5559
5775
      </funcsynopsis>
5560
5776
    </para>
5561
5777
 
5562
5778
    <para>
5563
 
      Deprecated.  Use the new name, &plbop;, for this function instead.
 
5779
    Parse command-line arguments.
5564
5780
    </para>
5565
5781
 
 
5782
    <variablelist>
 
5783
      <varlistentry>
 
5784
        <term>
 
5785
          <parameter>p_argc</parameter>
 
5786
          (<literal>int *</literal>, input)
 
5787
        </term>
 
5788
        <listitem>
 
5789
          <para>
 
5790
            pointer to number of arguments.
 
5791
          </para>
 
5792
        </listitem>
 
5793
      </varlistentry>
 
5794
      <varlistentry>
 
5795
        <term>
 
5796
          <parameter>argv</parameter>
 
5797
          (<literal>char **</literal>, input)
 
5798
        </term>
 
5799
        <listitem>
 
5800
          <para>
 
5801
            Pointer to character array containing
 
5802
            <literal><parameter>*p_argc</parameter></literal> command-line
 
5803
            arguments.
 
5804
          </para>
 
5805
        </listitem>
 
5806
      </varlistentry>
 
5807
      <varlistentry>
 
5808
        <term>
 
5809
          <parameter>mode</parameter>
 
5810
          (<literal>PLINT</literal>, input)
 
5811
        </term>
 
5812
        <listitem>
 
5813
          <para>
 
5814
            Parsing mode with the following possibilities:
 
5815
<itemizedlist>
 
5816
<listitem>
 
5817
<para>
 
5818
PL_PARSE_FULL (1) -- Full parsing of command line and all error messages
 
5819
enabled, including program exit when an error occurs.  Anything on the
 
5820
command line that isn't recognized as a valid option or option argument is
 
5821
flagged as an error.
 
5822
</para>
 
5823
</listitem>
 
5824
<listitem>
 
5825
<para>
 
5826
PL_PARSE_QUIET (2) -- Turns off all output except in the case of errors.
 
5827
</para>
 
5828
</listitem>
 
5829
<listitem>
 
5830
<para>
 
5831
PL_PARSE_NODELETE (4) -- Turns off deletion of processed arguments.
 
5832
</para>
 
5833
</listitem>
 
5834
<listitem>
 
5835
<para>
 
5836
PL_PARSE_SHOWALL (8) -- Show invisible options
 
5837
</para>
 
5838
</listitem>
 
5839
<listitem>
 
5840
<para>
 
5841
PL_PARSE_NOPROGRAM (32) -- Specified if argv[0] is NOT a pointer to the
 
5842
program name.
 
5843
</para>
 
5844
</listitem>
 
5845
<listitem>
 
5846
<para>
 
5847
PL_PARSE_NODASH (64) -- Set if leading dash is NOT required.
 
5848
</para>
 
5849
</listitem>
 
5850
<listitem>
 
5851
<para>
 
5852
PL_PARSE_SKIP (128) -- Set to quietly skip over any unrecognized args.
 
5853
</para>
 
5854
</listitem>
 
5855
</itemizedlist>
 
5856
          </para>
 
5857
        </listitem>
 
5858
      </varlistentry>
 
5859
    </variablelist>
 
5860
 
5566
5861
  </sect1>
5567
5862
 
5568
5863
  <sect1 id="plpat" renderas="sect3">
5634
5929
      </varlistentry>
5635
5930
    </variablelist>
5636
5931
 
5637
 
  </sect1>
 
5932
    </sect1>
5638
5933
 
5639
5934
  <sect1 id="plpoin" renderas="sect3">
5640
5935
    <title>
5915
6210
      <varlistentry>
5916
6211
        <term>
5917
6212
          <parameter>draw</parameter>
5918
 
          (<literal>PLINT *</literal>, input)
 
6213
          (<literal>PLBOOL *</literal>, input)
5919
6214
        </term>
5920
6215
        <listitem>
5921
6216
          <para>
5930
6225
      <varlistentry>
5931
6226
        <term>
5932
6227
          <parameter>ifcc</parameter>
5933
 
          (<literal>PLINT</literal>, input)
 
6228
          (<literal>PLBOOL</literal>, input)
5934
6229
        </term>
5935
6230
        <listitem>
5936
6231
    <para>
5937
 
      If <literal><parameter>ifcc</parameter>=1</literal>
 
6232
      If <literal><parameter>ifcc</parameter></literal> is true
5938
6233
      the directionality of the polygon is determined by assuming the points
5939
 
      are laid out in a counter-clockwise order.
5940
 
      If <literal><parameter>ifcc</parameter>=0</literal>
 
6234
      are laid out in a counter-clockwise order.  Otherwise,
5941
6235
      the directionality of the polygon is determined by assuming the points
5942
6236
      are laid out in a clockwise order.
5943
6237
    </para>
6183
6477
 
6184
6478
  </sect1>
6185
6479
 
6186
 
  <sect1 id="plrgb" renderas="sect3">
6187
 
    <title>
6188
 
      <function>plrgb</function>: Set line color by red, green
6189
 
    </title>
6190
 
 
6191
 
    <para>
6192
 
      <funcsynopsis>
6193
 
      <funcprototype>
6194
 
        <funcdef>
6195
 
           <function>plrgb</function>
6196
 
        </funcdef>
6197
 
        <paramdef><parameter>r</parameter></paramdef>
6198
 
        <paramdef><parameter>g</parameter></paramdef>
6199
 
        <paramdef><parameter>b</parameter></paramdef>
6200
 
      </funcprototype>
6201
 
      </funcsynopsis>
6202
 
    </para>
6203
 
 
6204
 
    <para>
6205
 
      Set line color by red, green, blue from  0. to 1.  Do
6206
 
<emphasis>not</emphasis> use this.
6207
 
Only retained for backward compatibility. Use the function plscol0
6208
 
instead.
6209
 
    </para>
6210
 
 
6211
 
    <variablelist>
6212
 
      <varlistentry>
6213
 
        <term>
6214
 
          <parameter>r</parameter>
6215
 
          (<literal>PLFLT</literal>, input)
6216
 
        </term>
6217
 
        <listitem>
6218
 
          <para>
6219
 
            NEEDS DOCUMENTATION
6220
 
          </para>
6221
 
        </listitem>
6222
 
      </varlistentry>
6223
 
      <varlistentry>
6224
 
        <term>
6225
 
          <parameter>g</parameter>
6226
 
          (<literal>PLFLT</literal>, input)
6227
 
        </term>
6228
 
        <listitem>
6229
 
          <para>
6230
 
            NEEDS DOCUMENTATION
6231
 
          </para>
6232
 
        </listitem>
6233
 
      </varlistentry>
6234
 
      <varlistentry>
6235
 
        <term>
6236
 
          <parameter>b</parameter>
6237
 
          (<literal>PLFLT</literal>, input)
6238
 
        </term>
6239
 
        <listitem>
6240
 
          <para>
6241
 
            NEEDS DOCUMENTATION
6242
 
          </para>
6243
 
        </listitem>
6244
 
      </varlistentry>
6245
 
    </variablelist>
6246
 
 
6247
 
  </sect1>
6248
 
 
6249
 
  <sect1 id="plrgb1" renderas="sect3">
6250
 
    <title>
6251
 
      <function>plrgb1</function>: Set line color by 8-bit RGB values
6252
 
    </title>
6253
 
 
6254
 
    <para>
6255
 
      <funcsynopsis>
6256
 
      <funcprototype>
6257
 
        <funcdef>
6258
 
           <function>plrgb1</function>
6259
 
        </funcdef>
6260
 
        <paramdef><parameter>r</parameter></paramdef>
6261
 
        <paramdef><parameter>g</parameter></paramdef>
6262
 
        <paramdef><parameter>b</parameter></paramdef>
6263
 
      </funcprototype>
6264
 
      </funcsynopsis>
6265
 
    </para>
6266
 
 
6267
 
    <para>
6268
 
      Set line color by 8-bit RGB values.  Do <emphasis>not</emphasis> use this.
6269
 
Only retained for backward compatibility. Use the function plscol0
6270
 
instead.
6271
 
    </para>
6272
 
 
6273
 
    <variablelist>
6274
 
      <varlistentry>
6275
 
        <term>
6276
 
          <parameter>r</parameter>
6277
 
          (<literal>PLINT</literal>, input)
6278
 
        </term>
6279
 
        <listitem>
6280
 
          <para>
6281
 
            NEEDS DOCUMENTATION
6282
 
          </para>
6283
 
        </listitem>
6284
 
      </varlistentry>
6285
 
      <varlistentry>
6286
 
        <term>
6287
 
          <parameter>g</parameter>
6288
 
          (<literal>PLINT</literal>, input)
6289
 
        </term>
6290
 
        <listitem>
6291
 
          <para>
6292
 
            NEEDS DOCUMENTATION
6293
 
          </para>
6294
 
        </listitem>
6295
 
      </varlistentry>
6296
 
      <varlistentry>
6297
 
        <term>
6298
 
          <parameter>b</parameter>
6299
 
          (<literal>PLINT</literal>, input)
6300
 
        </term>
6301
 
        <listitem>
6302
 
          <para>
6303
 
            NEEDS DOCUMENTATION
 
6480
  <sect1 id="plrgbhls" renderas="sect3">
 
6481
    <title>
 
6482
      <function>plrgbhls</function>: Convert RGB color to HLS
 
6483
    </title>
 
6484
 
 
6485
    <para>
 
6486
      <funcsynopsis>
 
6487
      <funcprototype>
 
6488
        <funcdef>
 
6489
           <function>plrgbhls</function>
 
6490
        </funcdef>
 
6491
        <paramdef><parameter>r</parameter></paramdef>
 
6492
        <paramdef><parameter>g</parameter></paramdef>
 
6493
        <paramdef><parameter>b</parameter></paramdef>
 
6494
        <paramdef><parameter>p_h</parameter></paramdef>
 
6495
        <paramdef><parameter>p_l</parameter></paramdef>
 
6496
        <paramdef><parameter>p_s</parameter></paramdef>
 
6497
      </funcprototype>
 
6498
      </funcsynopsis>
 
6499
    </para>
 
6500
 
 
6501
    <para>
 
6502
      Convert RGB color coordinates to HLS
 
6503
    </para>
 
6504
 
 
6505
    <variablelist>
 
6506
      <varlistentry>
 
6507
        <term>
 
6508
          <parameter>r</parameter>
 
6509
          (<literal>PLFLT</literal>, output)
 
6510
        </term>
 
6511
        <listitem>
 
6512
          <para>
 
6513
            Red intensity (0.0-1.0) of the colour
 
6514
          </para>
 
6515
        </listitem>
 
6516
      </varlistentry>
 
6517
      <varlistentry>
 
6518
        <term>
 
6519
          <parameter>g</parameter>
 
6520
          (<literal>PLFLT</literal>, output)
 
6521
        </term>
 
6522
        <listitem>
 
6523
          <para>
 
6524
            Green intensity (0.0-1.0) of the colour
 
6525
          </para>
 
6526
        </listitem>
 
6527
      </varlistentry>
 
6528
      <varlistentry>
 
6529
        <term>
 
6530
          <parameter>b</parameter>
 
6531
          (<literal>PLFLT</literal>, output)
 
6532
        </term>
 
6533
        <listitem>
 
6534
          <para>
 
6535
            Blue intensity (0.0-1.0) of the colour
 
6536
          </para>
 
6537
        </listitem>
 
6538
      </varlistentry>
 
6539
      <varlistentry>
 
6540
        <term>
 
6541
          <parameter>p_h</parameter>
 
6542
          (<literal>PLFLT *</literal>, input)
 
6543
        </term>
 
6544
        <listitem>
 
6545
          <para>
 
6546
            Pointer to hue, in degrees on the colour cone (0.0-360.0)
 
6547
          </para>
 
6548
        </listitem>
 
6549
      </varlistentry>
 
6550
      <varlistentry>
 
6551
        <term>
 
6552
          <parameter>p_l</parameter>
 
6553
          (<literal>PLFLT *</literal>, input)
 
6554
        </term>
 
6555
        <listitem>
 
6556
          <para>
 
6557
            Pointer to lightness, expressed as a fraction of the axis of the colour
 
6558
            cone (0.0-1.0)
 
6559
          </para>
 
6560
        </listitem>
 
6561
      </varlistentry>
 
6562
      <varlistentry>
 
6563
        <term>
 
6564
          <parameter>p_s</parameter>
 
6565
          (<literal>PLFLT *</literal>, input)
 
6566
        </term>
 
6567
        <listitem>
 
6568
          <para>
 
6569
            Pointer to saturation, expressed as a fraction of the radius of the
 
6570
            colour cone (0.0-1.0)
6304
6571
          </para>
6305
6572
        </listitem>
6306
6573
      </varlistentry>
6617
6884
    </para>
6618
6885
 
6619
6886
<para> The hue is interpolated around the "front" of the color wheel
6620
 
      (red&lt;->green&lt;->blue&lt;->red) unless the "rev" flag is set, in
6621
 
      which case interpolation (between the <literal>i</literal> and
 
6887
      (red&lt;->green&lt;->blue&lt;->red) unless the "rev" flag is set to true,
 
6888
      in which case interpolation (between the <literal>i</literal> and
6622
6889
      <literal>i + 1</literal> control point for <literal>rev[i]</literal>)
6623
6890
      proceeds around the back (reverse) side.  Specifying rev=NULL is
6624
 
      equivalent to setting rev[]=0 for every control point. </para>
 
6891
      equivalent to setting rev[]= false for every control point. </para>
6625
6892
 
6626
6893
<para>
6627
6894
<table frame="none"><title> Bounds on coordinates</title>
6642
6909
      <varlistentry>
6643
6910
        <term>
6644
6911
          <parameter>itype</parameter>
6645
 
          (<literal>PLINT</literal>, input)
 
6912
          (<literal>PLBOOL</literal>, input)
6646
6913
        </term>
6647
6914
        <listitem>
6648
6915
          <para>
6649
 
            0: HLS, 1: RGB
 
6916
            true: RGB, false: HLS.
6650
6917
          </para>
6651
6918
        </listitem>
6652
6919
      </varlistentry>
6709
6976
      <varlistentry>
6710
6977
        <term>
6711
6978
          <parameter>rev</parameter>
6712
 
          (<literal>PLINT *</literal>, input)
 
6979
          (<literal>PLBOOL: *</literal>, input)
6713
6980
        </term>
6714
6981
        <listitem>
6715
6982
          <para>
6716
 
            reverse flag for each control point (<literal>rev[i]</literal> refers
 
6983
            reverse flag for each control point. (<literal>rev[i]</literal> 
 
6984
            refers
6717
6985
            to the interpolation interval between the <literal>i</literal> and
6718
6986
            <literal>i + 1</literal> control points).
6719
6987
          </para>
7423
7691
 
7424
7692
    <para>
7425
7693
    Set the escape character for text strings.  From C (in contrast to
7426
 
    fortran, see &plsescfortran;) you pass
 
7694
    Fortran 77, see &plsescfortran77;) you pass
7427
7695
    <literal><parameter>esc</parameter></literal> as a character.
7428
7696
    Only selected characters are allowed to prevent the user from shooting
7429
7697
    himself in the foot (For example, a <quote>\</quote> isn't allowed since it conflicts with C's use
7609
7877
 
7610
7878
  </sect1>
7611
7879
 
 
7880
  <sect1 id="plsfci" renderas="sect3">
 
7881
    <title>
 
7882
      <function>plsfci</function>: Set FCI (font characterization integer)
 
7883
    </title>
 
7884
 
 
7885
    <para>
 
7886
      <funcsynopsis>
 
7887
      <funcprototype>
 
7888
        <funcdef>
 
7889
          <function>plsfci</function>
 
7890
        </funcdef>
 
7891
        <paramdef><parameter>fci</parameter></paramdef>
 
7892
      </funcprototype>
 
7893
      </funcsynopsis>
 
7894
    </para>
 
7895
 
 
7896
    <para>
 
7897
      Sets font characteristics to be used at the start of the next string
 
7898
      using the FCI approach.
 
7899
      See <xref linkend="fci"/> for more information.
 
7900
    </para>
 
7901
 
 
7902
    <variablelist>
 
7903
      <varlistentry>
 
7904
        <term>
 
7905
          <parameter>fci</parameter>
 
7906
          (<literal>PLUNICODE</literal>, input)
 
7907
        </term>
 
7908
        <listitem>
 
7909
          <para>
 
7910
            PLUNICODE (unsigned 32-bit integer) value of FCI.
 
7911
          </para>
 
7912
        </listitem>
 
7913
      </varlistentry>
 
7914
    </variablelist>
 
7915
 
 
7916
  </sect1>
 
7917
 
7612
7918
  <sect1 id="plsfnam" renderas="sect3">
7613
7919
    <title>
7614
7920
      <function>plsfnam</function>: Set output file name
7873
8179
      <varlistentry>
7874
8180
        <term>
7875
8181
          <parameter>rectangular</parameter>
7876
 
          (<literal>PLINT</literal>, input)
 
8182
          (<literal>PLBOOL</literal>, input)
7877
8183
        </term>
7878
8184
        <listitem>
7879
8185
          <para>
7880
 
          Set <literal><parameter>rectangular</parameter></literal> to 1
 
8186
          Set <literal><parameter>rectangular</parameter></literal> to true
7881
8187
          if rectangles map to rectangles after coordinate transformation
7882
8188
          with <literal><parameter>pltrl</parameter></literal>.  Otherwise,
7883
 
          set <literal><parameter>rectangular</parameter></literal> to 0.
 
8189
          set <literal><parameter>rectangular</parameter></literal> to false.
7884
8190
          If <literal><parameter>rectangular</parameter></literal>
7885
 
          is set to 1, plshade tries to save time by
 
8191
          is set to true, plshade tries to save time by
7886
8192
          filling large rectangles.  This optimization fails if
7887
8193
          the coordinate transformation distorts the shape of rectangles.
7888
 
          For example a plot in polor coordinates has to have rectangular
7889
 
          set to 0.
 
8194
          For example a plot in polor coordinates has to have 
 
8195
          <literal><parameter>rectangular</parameter></literal>
 
8196
          set to false.
7890
8197
          </para>
7891
8198
        </listitem>
7892
8199
      </varlistentry>
8158
8465
      <varlistentry>
8159
8466
        <term>
8160
8467
          <parameter>rectangular</parameter>
8161
 
          (<literal>PLINT</literal>, input)
 
8468
          (<literal>PLBOOL</literal>, input)
8162
8469
        </term>
8163
8470
        <listitem>
8164
8471
          <para>
8474
8781
      <varlistentry>
8475
8782
        <term>
8476
8783
          <parameter>rectangular</parameter>
8477
 
          (<literal>PLINT</literal>, input)
 
8784
          (<literal>PLBOOL</literal>, input)
8478
8785
        </term>
8479
8786
        <listitem>
8480
8787
          <para>
8481
 
          Set <literal><parameter>rectangular</parameter></literal> to 1
 
8788
          Set <literal><parameter>rectangular</parameter></literal> to true
8482
8789
          if rectangles map to rectangles after coordinate transformation
8483
8790
          with <literal><parameter>pltrl</parameter></literal>.  Otherwise,
8484
 
          set <literal><parameter>rectangular</parameter></literal> to 0.
 
8791
          set <literal><parameter>rectangular</parameter></literal> to false.
8485
8792
          If <literal><parameter>rectangular</parameter></literal>
8486
 
          is set to 1, plshade tries to save time by
 
8793
          is set to true, plshade tries to save time by
8487
8794
          filling large rectangles.  This optimization fails if
8488
8795
          the coordinate transformation distorts the shape of rectangles.
8489
 
          For example a plot in polor coordinates has to have rectangular
8490
 
          set to 0.
 
8796
          For example a plot in polor coordinates has to have
 
8797
          <literal><parameter>rectangular</parameter></literal>
 
8798
          set to false.
8491
8799
          </para>
8492
8800
        </listitem>
8493
8801
      </varlistentry>
8871
9179
      <varlistentry>
8872
9180
        <term>
8873
9181
          <parameter>pause</parameter>
8874
 
          (<literal>PLINT</literal>, input)
 
9182
          (<literal>PLBOOL</literal>, input)
8875
9183
        </term>
8876
9184
        <listitem>
8877
9185
          <para>
8878
 
            If <literal><parameter>pause</parameter></literal> = 1 there
 
9186
            If <literal><parameter>pause</parameter></literal> is true there
8879
9187
            will be a pause on end-of-page for those drivers which support
8880
9188
            this.  Otherwise there is no pause.
8881
9189
          </para>
8926
9234
 
8927
9235
  <sect1 id="plssub" renderas="sect3">
8928
9236
    <title>
8929
 
      <function>plssub</function>: Set the number of subwindows in x and y
 
9237
      <function>plssub</function>: Set the number of subpages in x and y
8930
9238
    </title>
8931
9239
 
8932
9240
    <para>
8942
9250
    </para>
8943
9251
 
8944
9252
    <para>
8945
 
      Set the number of subwindows in x and y.
 
9253
      Set the number of subpages in x and y.
8946
9254
    </para>
8947
9255
 
8948
9256
    <variablelist>
9048
9356
      device.  If only one device is enabled when PLplot is installed,
9049
9357
      &plstar; will issue no prompt.  The output device is divided into
9050
9358
      <literal><parameter>nx</parameter></literal> by
9051
 
      <literal><parameter>ny</parameter></literal> sub-pages, each of which
 
9359
      <literal><parameter>ny</parameter></literal> subpages, each of which
9052
9360
      may be used independently.  The subroutine &pladv; is used to advance
9053
9361
      from one subpage to the next.
9054
9362
    </para>
9109
9417
      begins with ``?'', the prompted startup of &plstar; is used.  This
9110
9418
      routine also divides the output device into
9111
9419
      <literal><parameter>nx</parameter></literal> by
9112
 
      <literal><parameter>ny</parameter></literal> sub-pages, each of which
 
9420
      <literal><parameter>ny</parameter></literal> subpages, each of which
9113
9421
      may be used independently.  The subroutine &pladv; is used to advance
9114
9422
      from one subpage to the next.
9115
9423
    </para>
9391
9699
      <varlistentry>
9392
9700
        <term>
9393
9701
          <parameter>y_ascl</parameter>
9394
 
          (<literal>PLINT</literal>, input)
 
9702
          (<literal>PLBOOL</literal>, input)
9395
9703
        </term>
9396
9704
        <listitem>
9397
9705
          <para>
9398
 
          Autoscale y between x jumps (1) or not (0).
 
9706
          Autoscale y between x jumps if
 
9707
          <literal><parameter>y_ascl</parameter></literal> is true,
 
9708
          otherwise not.
9399
9709
          </para>
9400
9710
        </listitem>
9401
9711
      </varlistentry>
9402
9712
      <varlistentry>
9403
9713
        <term>
9404
9714
          <parameter>acc</parameter>
9405
 
          (<literal>PLINT</literal>, input)
 
9715
          (<literal>PLBOOL</literal>, input)
9406
9716
        </term>
9407
9717
        <listitem>
9408
9718
          <para>
9409
 
            Accumulate strip plot (1) or slide (0).
 
9719
            Accumulate strip plot if
 
9720
            <literal><parameter>acc</parameter></literal> is true,
 
9721
            otherwise slide display.
9410
9722
          </para>
9411
9723
        </listitem>
9412
9724
      </varlistentry>
9845
10157
      <varlistentry>
9846
10158
        <term>
9847
10159
          <parameter>fill</parameter>
9848
 
          (<literal>PLINT</literal>,input)
 
10160
          (<literal>PLBOOL</literal>,input)
9849
10161
        </term>
9850
10162
        <listitem>
9851
10163
          <para>
9852
 
            If <literal><parameter>fill</parameter> = 0</literal> then the
9853
 
            arrow is open, if <literal><parameter>fill</parameter> = 1</literal>
9854
 
            then the arrow is filled.
 
10164
            If <literal><parameter>fill</parameter></literal> is true then the
 
10165
            arrow is closed, if <literal><parameter>fill</parameter></literal>
 
10166
            is false then the arrow is open.
9855
10167
          </para>
9856
10168
        </listitem>
9857
10169
      </varlistentry>
10891
11203
    </para>
10892
11204
 
10893
11205
    <para>
10894
 
      Enter (mode !=0) or leave (mode == 0) xor mode for those drivers
 
11206
      Enter (when <literal><parameter>mode</parameter></literal> is true) 
 
11207
      or leave (when <literal><parameter>mode</parameter></literal> is false)
 
11208
      xor mode for those drivers
10895
11209
      (e.g., the xwin driver) that support it.  Enables erasing plots by
10896
11210
      drawing twice the same line, symbol, etc.  If driver is not capable
10897
 
      of xor operation returns status of 0.
 
11211
      of xor operation it returns a
 
11212
      <literal><parameter>status</parameter></literal> of false.
10898
11213
    </para>
10899
11214
 
10900
11215
    <variablelist>
10901
11216
      <varlistentry>
10902
11217
        <term>
10903
11218
          <parameter>mode</parameter>
10904
 
          (<literal>PLINT</literal>, input)
 
11219
          (<literal>PLBOOL</literal>, input)
10905
11220
        </term>
10906
11221
        <listitem>
10907
11222
          <para>
10908
 
          mode != 0 means enter xor mode and mode == 0 means leave xor
10909
 
          mode.
 
11223
          <literal><parameter>mode</parameter></literal> is true
 
11224
          means enter xor mode and 
 
11225
          <literal><parameter>mode</parameter></literal> is false
 
11226
          means leave xor mode.
10910
11227
          </para>
10911
11228
        </listitem>
10912
11229
      </varlistentry>
10913
11230
      <varlistentry>
10914
11231
        <term>
10915
11232
          <parameter>status</parameter>
10916
 
          (<literal>PLINT *</literal>, output)
 
11233
          (<literal>PLBOOL *</literal>, output)
10917
11234
        </term>
10918
11235
        <listitem>
10919
11236
          <para>
10920
 
          Pointer to status. Returned status == 1 (0) means driver is capable
10921
 
          (incapable) of xor mode.
 
11237
          Pointer to status. Returned 
 
11238
          <literal><parameter>mode</parameter></literal>status of true (false)
 
11239
          means driver is capable (incapable) of xor mode.
10922
11240
          </para>
10923
11241
        </listitem>
10924
11242
      </varlistentry>