From 6e22866c373b48dc4c7a7f42aad46847abb4f98b Mon Sep 17 00:00:00 2001 From: Uwe Steinmann Date: Fri, 3 Mar 2006 12:31:05 +0000 Subject: [PATCH] - completed the list of function parameters - added examples where needed git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@208537 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/ps/functions/ps-add-bookmark.xml | 4 +- reference/ps/functions/ps-add-launchlink.xml | 5 +- reference/ps/functions/ps-add-locallink.xml | 4 +- reference/ps/functions/ps-add-note.xml | 10 +- reference/ps/functions/ps-add-pdflink.xml | 4 +- reference/ps/functions/ps-add-weblink.xml | 6 +- reference/ps/functions/ps-arc.xml | 7 +- reference/ps/functions/ps-arcn.xml | 5 +- reference/ps/functions/ps-begin-page.xml | 23 ++- reference/ps/functions/ps-get-parameter.xml | 40 +++- reference/ps/functions/ps-get-value.xml | 4 +- reference/ps/functions/ps-hyphenate.xml | 48 ++++- reference/ps/functions/ps-lineto.xml | 70 ++++++- reference/ps/functions/ps-makespotcolor.xml | 73 +++++++- reference/ps/functions/ps-moveto.xml | 35 +++- reference/ps/functions/ps-new.xml | 9 +- reference/ps/functions/ps-open-file.xml | 6 +- reference/ps/functions/ps-open-image-file.xml | 56 +++++- reference/ps/functions/ps-open-image.xml | 97 +++++++++- reference/ps/functions/ps-place-image.xml | 57 +++++- reference/ps/functions/ps-rect.xml | 51 ++++- reference/ps/functions/ps-restore.xml | 23 ++- reference/ps/functions/ps-rotate.xml | 93 ++++++++- reference/ps/functions/ps-save.xml | 21 ++- reference/ps/functions/ps-scale.xml | 35 +++- .../ps/functions/ps-set-border-color.xml | 51 ++++- reference/ps/functions/ps-set-border-dash.xml | 44 ++++- .../ps/functions/ps-set-border-style.xml | 13 +- reference/ps/functions/ps-set-info.xml | 67 ++++++- reference/ps/functions/ps-set-parameter.xml | 35 +++- reference/ps/functions/ps-set-text-pos.xml | 76 +++++++- reference/ps/functions/ps-set-value.xml | 74 +++++--- reference/ps/functions/ps-setcolor.xml | 18 +- reference/ps/functions/ps-setdash.xml | 35 +++- reference/ps/functions/ps-setflat.xml | 5 +- reference/ps/functions/ps-setfont.xml | 38 +++- reference/ps/functions/ps-setgray.xml | 5 +- reference/ps/functions/ps-setlinecap.xml | 30 ++- reference/ps/functions/ps-setlinejoin.xml | 30 ++- reference/ps/functions/ps-setlinewidth.xml | 27 ++- reference/ps/functions/ps-setmiterlimit.xml | 32 +++- reference/ps/functions/ps-setpolydash.xml | 42 ++++- reference/ps/functions/ps-shading-pattern.xml | 36 +++- reference/ps/functions/ps-shading.xml | 9 +- reference/ps/functions/ps-shfill.xml | 32 +++- reference/ps/functions/ps-show-boxed.xml | 177 +++++++++--------- reference/ps/functions/ps-show-xy.xml | 43 ++++- reference/ps/functions/ps-show.xml | 34 +++- reference/ps/functions/ps-string-geometry.xml | 48 ++++- reference/ps/functions/ps-stringwidth.xml | 45 ++++- reference/ps/functions/ps-stroke.xml | 19 +- reference/ps/functions/ps-symbol-name.xml | 8 +- reference/ps/functions/ps-symbol-width.xml | 14 +- reference/ps/functions/ps-symbol.xml | 27 ++- reference/ps/functions/ps-translate.xml | 106 ++++++++++- 55 files changed, 1783 insertions(+), 223 deletions(-) diff --git a/reference/ps/functions/ps-add-bookmark.xml b/reference/ps/functions/ps-add-bookmark.xml index dd6397ca10..0de9f98ce0 100644 --- a/reference/ps/functions/ps-add-bookmark.xml +++ b/reference/ps/functions/ps-add-bookmark.xml @@ -1,5 +1,5 @@ - + @@ -53,7 +53,7 @@ parent - The parameter parent is another bookmark which + A bookmark previously created by this function which is used as the parent of the new bookmark. diff --git a/reference/ps/functions/ps-add-launchlink.xml b/reference/ps/functions/ps-add-launchlink.xml index f67d8b098e..c94dfc2012 100644 --- a/reference/ps/functions/ps-add-launchlink.xml +++ b/reference/ps/functions/ps-add-launchlink.xml @@ -1,5 +1,5 @@ - + @@ -20,7 +20,8 @@ Places a hyperlink at the given position pointing to a file program - which is being started when clicked on. The hyperlink start is a rectangle + which is being started when clicked on. The hyperlink's source position + is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. diff --git a/reference/ps/functions/ps-add-locallink.xml b/reference/ps/functions/ps-add-locallink.xml index fbab904bb5..94f42e30dd 100644 --- a/reference/ps/functions/ps-add-locallink.xml +++ b/reference/ps/functions/ps-add-locallink.xml @@ -1,5 +1,5 @@ - + @@ -25,7 +25,7 @@ in a document has number 1. - The hyperlink start is a rectangle with its lower left corner at + The hyperlink's source position is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. diff --git a/reference/ps/functions/ps-add-note.xml b/reference/ps/functions/ps-add-note.xml index f06ccbc8f0..02f3483979 100644 --- a/reference/ps/functions/ps-add-note.xml +++ b/reference/ps/functions/ps-add-note.xml @@ -1,5 +1,5 @@ - + @@ -23,9 +23,15 @@ Adds a note at a certain position on the page. Notes are like little +<<<<<<< ps-add-note.xml + rectangular sheets with text on it, which can be placed anywhere on + a page. They + are shown either folded or unfolded. If unfolded, the specified icon +======= rectangular sheets with text on it, which can be place somewhere on a page. The notes are shown either folded or unfolded. If unfolded the specified icon +>>>>>>> 1.4 is used as placeholder. @@ -113,7 +119,7 @@ If open is unequal to zero the note will - be shown unfolded by the pdf viewer. + be shown unfolded after opening the document with a pdf viewer. diff --git a/reference/ps/functions/ps-add-pdflink.xml b/reference/ps/functions/ps-add-pdflink.xml index e4ec279434..897c108869 100644 --- a/reference/ps/functions/ps-add-pdflink.xml +++ b/reference/ps/functions/ps-add-pdflink.xml @@ -1,5 +1,5 @@ - + @@ -26,7 +26,7 @@ first page in a document has number 1. - The hyperlink start is a rectangle with its lower left corner at + The hyperlink's source position is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. diff --git a/reference/ps/functions/ps-add-weblink.xml b/reference/ps/functions/ps-add-weblink.xml index de1ad89fdc..30a67f8b6d 100644 --- a/reference/ps/functions/ps-add-weblink.xml +++ b/reference/ps/functions/ps-add-weblink.xml @@ -1,5 +1,5 @@ - + @@ -20,7 +20,7 @@ Places a hyperlink at the given position pointing to a web page. The - hyperlink start is a rectangle with its lower left corner at + hyperlink's source position is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin @@ -83,7 +83,7 @@ The url of the hyperlink to be opened when clicking on - this link. + this link, e.g. http://www.php.net. diff --git a/reference/ps/functions/ps-arc.xml b/reference/ps/functions/ps-arc.xml index 95ede15935..3bf9a0f53f 100644 --- a/reference/ps/functions/ps-arc.xml +++ b/reference/ps/functions/ps-arc.xml @@ -1,5 +1,5 @@ - + @@ -22,7 +22,8 @@ Draws a portion of a circle with at middle point at (x, y). The arc starts at an angle of alpha and ends at an angle of - beta. It is drawn counterclockwise. The subpath added + beta. It is drawn counterclockwise (use + ps_arcn to draw clockwise). The subpath added to the current path starts on the arc at angle alpha and ends on the arc at angle beta. @@ -69,7 +70,7 @@ alpha - The starting angle given in degrees. + The start angle given in degrees. diff --git a/reference/ps/functions/ps-arcn.xml b/reference/ps/functions/ps-arcn.xml index 872bcfd812..c79be601cc 100644 --- a/reference/ps/functions/ps-arcn.xml +++ b/reference/ps/functions/ps-arcn.xml @@ -1,5 +1,5 @@ - + @@ -22,7 +22,8 @@ Draws a portion of a circle with at middle point at (x, y). The arc starts at an angle of alpha and ends at an angle of - beta. It is drawn clockwise. The subpath added to + beta. It is drawn clockwise (use + ps_arc to draw counterclockwise). The subpath added to the current path starts on the arc at angle beta and ends on the arc at angle alpha. diff --git a/reference/ps/functions/ps-begin-page.xml b/reference/ps/functions/ps-begin-page.xml index 04072d6292..3cd20a42f0 100644 --- a/reference/ps/functions/ps-begin-page.xml +++ b/reference/ps/functions/ps-begin-page.xml @@ -1,5 +1,5 @@ - + @@ -26,6 +26,15 @@ can set the size for each page indiviually. The resulting PDF document will have different page sizes. + + Though PostScript does not know different page sizes, pslib places + a bounding box for each page into the document. This size is evaluated + by some PostScript viewers and will have precedence over the BoundingBox + in the Header of the document. This can lead to unexpected results when + you set a BoundingBox whose lower left corner is not (0, 0), because the + bounding box of the page will always have a lower left corner (0, 0) + and overwrites the global setting. + Each page is encapsulated into save/restore. This means, that most of the settings made on one page will not be retained on the next page. @@ -34,8 +43,8 @@ If there is up to the first call of ps_begin_page no call of ps_findfont, then the header of the PostScript document will be output and the bounding box will be set to the size of - the first page. If ps_findfont was called before, then - the + the first page. The lower left corner of the bounding box is set to (0, 0). + If ps_findfont was called before, then the header has been output already, and the document will not have a valid bounding box. In order to prevent this, one should call ps_set_info to set the info field @@ -43,6 +52,14 @@ before any ps_findfont or ps_begin_page calls. + + + Upt to version 0.2.6 of pslib, this function will always overwrite + the BoundingBox and Orientation, if it has been set before with + ps_set_info and ps_findfont + has not been called before. + + diff --git a/reference/ps/functions/ps-get-parameter.xml b/reference/ps/functions/ps-get-parameter.xml index 1725803c9d..9d2d95a5e1 100644 --- a/reference/ps/functions/ps-get-parameter.xml +++ b/reference/ps/functions/ps-get-parameter.xml @@ -1,5 +1,5 @@ - + @@ -93,6 +93,44 @@ + + linebreak + + + Only used if text is output with ps_show_boxed. + If set to true a carriage return will add a line + break. + + + + + parbreak + + + Only used if text is output with ps_show_boxed. + If set to true a carriage return will start + a new paragraph. + + + + + hyphenation + + + Only used if text is output with ps_show_boxed. + If set to true the paragraph will be hyphenated + if a hypen dictionary is set and exists. + + + + + hyphendict + + + Filename of the dictionary used for hyphenation pattern. + + + diff --git a/reference/ps/functions/ps-get-value.xml b/reference/ps/functions/ps-get-value.xml index 85d9045e70..d6bd5498fe 100644 --- a/reference/ps/functions/ps-get-value.xml +++ b/reference/ps/functions/ps-get-value.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,7 @@ floatmodifier Gets several values which were set by - ps_set_value. Parameters are by definition float values. + ps_set_value. Values are by definition float values. The parameter name can have the following values. diff --git a/reference/ps/functions/ps-hyphenate.xml b/reference/ps/functions/ps-hyphenate.xml index 02762d95db..0d345ae823 100644 --- a/reference/ps/functions/ps-hyphenate.xml +++ b/reference/ps/functions/ps-hyphenate.xml @@ -1,5 +1,5 @@ - + @@ -16,13 +16,14 @@ Hyphenates the passed word. ps_hyphenate evaluates the - value hyphenminchars and the parameter hyphendict. hyphendict must be set - before calling this function. + value hyphenminchars set by (ps_set_value) and + the parameter hyphendict (set by ps_set_parameter). + hyphendict must be set before calling this function. This function requires the locale category LC_CTYPE to be set properly. This is done when the extension is initialized by using the environment - variables. On Unix systems read the man page of locale. + variables. On Unix systems read the man page of locale for more information. @@ -34,7 +35,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -53,6 +55,42 @@ + + &reftitle.returnvalues; + + An array of integers indicating the position of possible breaks in + the text or &false; in case of an error. + + + + + &reftitle.examples; + + + Hyphennate a text + + +]]> + + + This example should output Ko-ordi-na-ten-sys-tem. + + + + + &reftitle.seealso; diff --git a/reference/ps/functions/ps-lineto.xml b/reference/ps/functions/ps-lineto.xml index 94b71c7d46..af2ebe1ada 100644 --- a/reference/ps/functions/ps-lineto.xml +++ b/reference/ps/functions/ps-lineto.xml @@ -1,5 +1,5 @@ - + @@ -22,6 +22,39 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + x + + + x-coordinate of the end point of the line. + + + + + y + + + y-coordinate of the end point of the line. + + + + + + + &reftitle.returnvalues; @@ -29,6 +62,41 @@ + + &reftitle.examples; + + + Drawing a rectangle + + +]]> + + + + + &reftitle.seealso; diff --git a/reference/ps/functions/ps-makespotcolor.xml b/reference/ps/functions/ps-makespotcolor.xml index 5d1e21833e..663e8a016e 100644 --- a/reference/ps/functions/ps-makespotcolor.xml +++ b/reference/ps/functions/ps-makespotcolor.xml @@ -1,5 +1,5 @@ - + @@ -19,7 +19,34 @@ Creates a spot color from the current fill color. The fill color must be defined in rgb, cmyk or gray colorspace. The spot color name can be an arbitrary name. A spot color can be set as any color with - ps_setcolor. + ps_setcolor. When the document is not printed + but displayed by an postscript viewer the given color in the specified + color space is use. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + name + + + Name of the spot color, e.g. Pantone 5565. + + + + @@ -30,6 +57,48 @@ + + &reftitle.examples; + + + Creating and using a spot color + + +]]> + + + This example creates the spot color "PANTONE 5565 C" which + is a darker green (olive) and fills a rectangle with 50% intensity. + + + + + &reftitle.seealso; diff --git a/reference/ps/functions/ps-moveto.xml b/reference/ps/functions/ps-moveto.xml index 0a7427e11c..a23fb8aab6 100644 --- a/reference/ps/functions/ps-moveto.xml +++ b/reference/ps/functions/ps-moveto.xml @@ -1,5 +1,5 @@ - + @@ -23,6 +23,39 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + x + + + x-coordinate of the point ot move to. + + + + + y + + + y-coordinate of the point to move to. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-new.xml b/reference/ps/functions/ps-new.xml index ef72baaf25..ba530c15c8 100644 --- a/reference/ps/functions/ps-new.xml +++ b/reference/ps/functions/ps-new.xml @@ -1,5 +1,5 @@ - + @@ -15,14 +15,17 @@ Creates a new document instance. It does not create the file on disk or in - memory. It just sets up everything. + memory, it just sets up everything. ps_new is usually + followed by a call of ps_open_file to actually create + the postscript document. &reftitle.returnvalues; - Resource of PostScript document or &false; on failure. + Resource of PostScript document or &false; on failure. The return value + is passed to all other functions as the first argument. diff --git a/reference/ps/functions/ps-open-file.xml b/reference/ps/functions/ps-open-file.xml index 9a721dd098..7efd620728 100644 --- a/reference/ps/functions/ps-open-file.xml +++ b/reference/ps/functions/ps-open-file.xml @@ -1,5 +1,5 @@ - + @@ -28,7 +28,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -36,6 +37,7 @@ filename + The name of the postscript file. If filename is not passed the document will be created in memory and all output will go straight to the browser. diff --git a/reference/ps/functions/ps-open-image-file.xml b/reference/ps/functions/ps-open-image-file.xml index e0dc9a1f42..94a6fbccf1 100644 --- a/reference/ps/functions/ps-open-image-file.xml +++ b/reference/ps/functions/ps-open-image-file.xml @@ -1,5 +1,5 @@ - + @@ -17,7 +17,59 @@ stringstringparam intintparam - &warn.undocumented.func; + + Loads an image for later use. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + type + + + The type of the image. Possible values are png, + jpeg, or eps. + + + + + filename + + + The name of the file containing the image data. + + + + + stringparam + + + Not used. + + + + + intparam + + + Not used. + + + + + diff --git a/reference/ps/functions/ps-open-image.xml b/reference/ps/functions/ps-open-image.xml index d9a0c6e990..0848fa14fa 100644 --- a/reference/ps/functions/ps-open-image.xml +++ b/reference/ps/functions/ps-open-image.xml @@ -1,5 +1,5 @@ - + @@ -25,7 +25,100 @@ Reads an image which is already available in memory. The parameter source is currently not evaluated and assumed to be - memory. + memory. The image data is a sequence of pixels starting + in th upper left corner and ending in the lower right corner. Each pixel + consists of components color components, and each + component has bpc bits. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + type + + + The type of the image. Possible values are png, + jpeg, or eps. + + + + + source + + + Not used. + + + + + data + + + The image data. + + + + + length + + + The length of the image data. + + + + + width + + + The width of the image. + + + + + height + + + The height of the image. + + + + + components + + + The number of components for each pixel. This can be + 1 (gray scale images), 3 (rgb images), or 4 (cmyk, rgba images). + + + + + bpc + + + Number of bits per component (quite often 8). + + + + + params + + + + + + diff --git a/reference/ps/functions/ps-place-image.xml b/reference/ps/functions/ps-place-image.xml index d6bc0974a0..9b40fab022 100644 --- a/reference/ps/functions/ps-place-image.xml +++ b/reference/ps/functions/ps-place-image.xml @@ -1,5 +1,5 @@ - + @@ -19,6 +19,61 @@ Places a formerly loaded image on the page. The image can be scaled. + If the image shall be rotated as well, you will have to rotate the + coordinate system before with ps_rotate. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + imageid + + + The resource identifier of the image as returned by + ps_open_image or + ps_open_image_file. + + + + + x + + + x-coordinate of the lower left corner of the image. + + + + + y + + + y-coordinate of the lower left corner of the image. + + + + + scale + + + The scaling factor for the image. A scale of 1.0 will result + in a resolution of 72 dpi, because each pixel is equivalent to + 1 point. + + + + diff --git a/reference/ps/functions/ps-rect.xml b/reference/ps/functions/ps-rect.xml index 905eba9e15..69506b7e0b 100644 --- a/reference/ps/functions/ps-rect.xml +++ b/reference/ps/functions/ps-rect.xml @@ -1,5 +1,5 @@ - + @@ -27,6 +27,55 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + x + + + x-coordinate of the lower left corner of the rectangle. + + + + + y + + + y-coordinate of the lower left corner of the rectangle. + + + + + width + + + The width of the image. + + + + + height + + + The height of the image. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-restore.xml b/reference/ps/functions/ps-restore.xml index e9fd104c31..1308994065 100644 --- a/reference/ps/functions/ps-restore.xml +++ b/reference/ps/functions/ps-restore.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,26 @@ Restores a previously saved graphics context. Any call of ps_save must be accompanied by a call to - ps_restore. + ps_restore. All coordinate transformations, line + style settings, color settings, etc. are being restored to the state + before the call of ps_save. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + diff --git a/reference/ps/functions/ps-rotate.xml b/reference/ps/functions/ps-rotate.xml index 98dc5bc111..02bb4be7fd 100644 --- a/reference/ps/functions/ps-rotate.xml +++ b/reference/ps/functions/ps-rotate.xml @@ -1,5 +1,5 @@ - + @@ -19,6 +19,31 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + rot + + + Angle of rotation in degree. + + + + + + + &reftitle.returnvalues; @@ -26,6 +51,72 @@ + + &reftitle.examples; + + + Rotation of the coordinate system + + +]]> + + + The above example illustrates a very common way of rotating a + graphic (in this case just a rectangle) by simply rotating the + coordinate system. Since the graphic's coordinate system assumes + (0,0) to be the origin, the page coordinate system is also translated + to place the graphics not on the edge of the page. Pay attention + to the order of ps_translate and + ps_rotate. In the above case the rectancle is + rotated around the point (100, 100) in the untranslated coordinate + system. Switching the two statements has a completely + different result. + + + In order to output the following text at the original position, all + modifications of the coordinate system are encapsulated in + ps_save and ps_restore. + + + + + &reftitle.seealso; diff --git a/reference/ps/functions/ps-save.xml b/reference/ps/functions/ps-save.xml index 810f6ea06c..eace18628f 100644 --- a/reference/ps/functions/ps-save.xml +++ b/reference/ps/functions/ps-save.xml @@ -1,5 +1,5 @@ - + @@ -15,11 +15,28 @@ Saves the current graphics context, containing colors, translation and - rotation settings and some more. A save context can be restored with + rotation settings and some more. A saved context can be restored with ps_restore. + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-scale.xml b/reference/ps/functions/ps-scale.xml index 511b0f399d..b67e33b6cb 100644 --- a/reference/ps/functions/ps-scale.xml +++ b/reference/ps/functions/ps-scale.xml @@ -1,5 +1,5 @@ - + @@ -20,6 +20,39 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + x + + + Scaling factor in horizontal direction. + + + + + y + + + Scaling factor in vertical direction. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-set-border-color.xml b/reference/ps/functions/ps-set-border-color.xml index 295fb66885..10dc6936cc 100644 --- a/reference/ps/functions/ps-set-border-color.xml +++ b/reference/ps/functions/ps-set-border-color.xml @@ -1,5 +1,5 @@ - + @@ -17,8 +17,53 @@ floatblue - Annotations like the starting points of links are surrounded by a rectangle. - This function sets the color of the border line. + Links added with one of the functions ps_add_weblink, + ps_add_pdflink, etc. will be displayed with a + surounded rectangle when the postscript document is converted to + pdf and viewed in a pdf viewer. This rectangle is not visible in + the postscript document. + This function sets the color of the rectangle's border line. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + red + + + The red component of the border color. + + + + + green + + + The green component of the border color. + + + + + blue + + + The blue component of the border color. + + + + diff --git a/reference/ps/functions/ps-set-border-dash.xml b/reference/ps/functions/ps-set-border-dash.xml index 7ada52675f..e8e7c4f7d5 100644 --- a/reference/ps/functions/ps-set-border-dash.xml +++ b/reference/ps/functions/ps-set-border-dash.xml @@ -1,5 +1,5 @@ - + @@ -16,8 +16,46 @@ floatwhite - Annotations like the starting points of links are surrounded by a rectangle. - This function sets the black and white portion of a dashed border line. + Links added with one of the functions ps_add_weblink, + ps_add_pdflink, etc. will be displayed with a + surounded rectangle when the postscript document is converted to + pdf and viewed in a pdf viewer. This rectangle is not visible in + the postscript document. + This function sets the length of the black and white portion of a + dashed border line. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + black + + + The length of the dash. + + + + + white + + + The length of the gap between dashes. + + + + diff --git a/reference/ps/functions/ps-set-border-style.xml b/reference/ps/functions/ps-set-border-style.xml index c491d0c1f0..ef470cc60a 100644 --- a/reference/ps/functions/ps-set-border-style.xml +++ b/reference/ps/functions/ps-set-border-style.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,11 @@ floatwidth - Annotations like the starting points of links are surrounded by a rectangle. + Links added with one of the functions ps_add_weblink, + ps_add_pdflink, etc. will be displayed with a + surounded rectangle when the postscript document is converted to + pdf and viewed in a pdf viewer. This rectangle is not visible in + the postscript document. This function sets the appearance and width of the border line. @@ -29,7 +33,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -46,7 +51,7 @@ width - + The line width of the border. diff --git a/reference/ps/functions/ps-set-info.xml b/reference/ps/functions/ps-set-info.xml index eebc4c2dc6..8c1230f71b 100644 --- a/reference/ps/functions/ps-set-info.xml +++ b/reference/ps/functions/ps-set-info.xml @@ -1,5 +1,5 @@ - + @@ -17,12 +17,9 @@ Sets certain information fields of the document. This fields will be shown - as a comment in the header of the PostScript file. The values which can be - set are Keywords, Subject, - Title, Creator, - Author, BoundingBox, and - Orientation. Be aware that some of them has a meaning to - PostScript viewers. + as a comment in the header of the PostScript file. If the document is + converted to pdf this fields will also be used for the document + information. The BoundingBox is usually set to the value given to the @@ -30,6 +27,62 @@ been called before. In such cases the BoundingBox would be left unset unless you set it explicitly with this function. + + This function will have no effect anymore when the header of the postscript + file has been already written. I must be called before the first page + or the first call of ps_findfont. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + key + + + The name of the information field to set. The values which can be + set are Keywords, Subject, + Title, Creator, + Author, BoundingBox, and + Orientation. Be aware that some of them has a + meaning to PostScript viewers. + + + + + value + + + The value of the information field. The field + Orientation can be set to either + Portrait or Landscape. The + BoundingBox is a string consisting of for numbers + The first two numbers are the coordinates of the lower left corner of + the page. The last two numbers are the coordinates of the upper + right corner. + + + + Upt to version 0.2.6 of pslib, the BoundingBox and Orientation + will be overwritten by ps_begin_page, + unless ps_findfont has been called before. + + + + + + diff --git a/reference/ps/functions/ps-set-parameter.xml b/reference/ps/functions/ps-set-parameter.xml index e48ec8c0e8..598e94ba43 100644 --- a/reference/ps/functions/ps-set-parameter.xml +++ b/reference/ps/functions/ps-set-parameter.xml @@ -1,5 +1,5 @@ - + @@ -21,6 +21,39 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + name + + + For a list of possible names see ps_get_parameter. + + + + + value + + + The value of the parameter. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-set-text-pos.xml b/reference/ps/functions/ps-set-text-pos.xml index 80157d814b..addb5610c5 100644 --- a/reference/ps/functions/ps-set-text-pos.xml +++ b/reference/ps/functions/ps-set-text-pos.xml @@ -1,5 +1,5 @@ - + @@ -21,6 +21,44 @@ choosing textx respectively texty as the value name. + + If you want to output text at a certain position it is more convenient + to use ps_show_xy instead of setting the text position + and calling ps_show. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + x + + + x-coordinate of the new text position. + + + + + y + + + y-coordinate of the new text position. + + + + + @@ -30,6 +68,42 @@ + + &reftitle.examples; + + + Placing text at a given position + + +]]> + + + + + &reftitle.seealso; diff --git a/reference/ps/functions/ps-set-value.xml b/reference/ps/functions/ps-set-value.xml index 8c31c9d0aa..47d93dab1d 100644 --- a/reference/ps/functions/ps-set-value.xml +++ b/reference/ps/functions/ps-set-value.xml @@ -1,5 +1,5 @@ - + @@ -24,45 +24,71 @@ &reftitle.parameters; - The name can be one of the following: - textrendering + psdoc - The way how text is shown. + Resource identifier of the postscript file + as returned by ps_new. - textx + name - The x coordinate for text output. + The name can be one of the following: + + + textrendering + + + The way how text is shown. + + + + + textx + + + The x coordinate for text output. + + + + + texty + + + The y coordinate for text output. + + + + + wordspacing + + + The distance between words relative to the width of a space. + + + + + leading + + + The distance between lines in pixels. + + + + - texty + value - The y coordinate for text output. - - - - - wordspacing - - - The distance between words relative to the width of a space. - - - - - leading - - - The distance between lines in pixels. + The value of the parameter. diff --git a/reference/ps/functions/ps-setcolor.xml b/reference/ps/functions/ps-setcolor.xml index c4a17db78e..3b7a9b5a2a 100644 --- a/reference/ps/functions/ps-setcolor.xml +++ b/reference/ps/functions/ps-setcolor.xml @@ -1,5 +1,5 @@ - + @@ -32,7 +32,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -62,7 +63,9 @@ c1 - + Depending on the colorspace this is either the red component (rgb), + the cyan component (cmyk), the gray value (gray), the identifier of + the spot color or the identifier of the pattern. @@ -70,7 +73,8 @@ c2 - + Depending on the colorspace this is either the green component (rgb), + the magenta component (cmyk). @@ -78,7 +82,8 @@ c3 - + Depending on the colorspace this is either the blue component (rgb), + the yellow component (cmyk). @@ -86,7 +91,8 @@ c4 - + This must only be set in cmyk colorspace and specifies the black + component. diff --git a/reference/ps/functions/ps-setdash.xml b/reference/ps/functions/ps-setdash.xml index a728194ae2..67365f61e1 100644 --- a/reference/ps/functions/ps-setdash.xml +++ b/reference/ps/functions/ps-setdash.xml @@ -1,5 +1,5 @@ - + @@ -20,6 +20,39 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + on + + + The length of the dash. + + + + + off + + + The length of the gap between dashes. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-setflat.xml b/reference/ps/functions/ps-setflat.xml index b1fb1dc1ee..80a37e5568 100644 --- a/reference/ps/functions/ps-setflat.xml +++ b/reference/ps/functions/ps-setflat.xml @@ -1,5 +1,5 @@ - + @@ -27,7 +27,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. diff --git a/reference/ps/functions/ps-setfont.xml b/reference/ps/functions/ps-setfont.xml index 2198f32466..b61b1e0bb7 100644 --- a/reference/ps/functions/ps-setfont.xml +++ b/reference/ps/functions/ps-setfont.xml @@ -1,5 +1,5 @@ - + @@ -18,7 +18,40 @@ Sets a font, which has to be loaded before with ps_findfont. Outputting text without setting a font - before results in an error. + results in an error. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + fontid + + + The font identifier as returned by ps_findfont. + + + + + size + + + The size of the font. + + + + @@ -34,6 +67,7 @@ ps_findfont + ps_set_text_pos for an example. diff --git a/reference/ps/functions/ps-setgray.xml b/reference/ps/functions/ps-setgray.xml index beacf14cc5..4322ea536e 100644 --- a/reference/ps/functions/ps-setgray.xml +++ b/reference/ps/functions/ps-setgray.xml @@ -1,5 +1,5 @@ - + @@ -28,7 +28,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. diff --git a/reference/ps/functions/ps-setlinecap.xml b/reference/ps/functions/ps-setlinecap.xml index c0d1004a5d..5cda41523d 100644 --- a/reference/ps/functions/ps-setlinecap.xml +++ b/reference/ps/functions/ps-setlinecap.xml @@ -1,5 +1,5 @@ - + @@ -19,6 +19,34 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + type + + + The type of line ends. Possible values are + PS_LINECAP_BUTT, + PS_LINECAP_ROUND, or + PS_LINECAP_SQUARED. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-setlinejoin.xml b/reference/ps/functions/ps-setlinejoin.xml index 10519590ef..1f9241ff24 100644 --- a/reference/ps/functions/ps-setlinejoin.xml +++ b/reference/ps/functions/ps-setlinejoin.xml @@ -1,5 +1,5 @@ - + @@ -19,6 +19,34 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + type + + + The way lines are joined. Possible values are + PS_LINEJOIN_MITER, + PS_LINEJOIN_ROUND, or + PS_LINEJOIN_BEVEL. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-setlinewidth.xml b/reference/ps/functions/ps-setlinewidth.xml index ee5073052d..0892c1ae65 100644 --- a/reference/ps/functions/ps-setlinewidth.xml +++ b/reference/ps/functions/ps-setlinewidth.xml @@ -1,5 +1,5 @@ - + @@ -19,6 +19,31 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + width + + + The width of lines in points. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-setmiterlimit.xml b/reference/ps/functions/ps-setmiterlimit.xml index d844000181..77caec9766 100644 --- a/reference/ps/functions/ps-setmiterlimit.xml +++ b/reference/ps/functions/ps-setmiterlimit.xml @@ -1,5 +1,5 @@ - + @@ -15,12 +15,40 @@ floatvalue - If two lines join in a small angle and the line join is set to miter, then + If two lines join in a small angle and the line join is set to + PS_LINEJOIN_MITER, then the resulting spike will be very long. The miter limit is the maximum ratio of the miter length (the length of the spike) and the line width. + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + value + + + The maximum ratio between the miter length and the line width. Larger + values (> 10) wil result in very long spikes when two lines meet + in a small angle. Keep the default unless you know what you are doing. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-setpolydash.xml b/reference/ps/functions/ps-setpolydash.xml index 27c4bc3b4a..2ce7d89441 100644 --- a/reference/ps/functions/ps-setpolydash.xml +++ b/reference/ps/functions/ps-setpolydash.xml @@ -1,5 +1,5 @@ - + @@ -29,7 +29,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -53,6 +54,43 @@ + + &reftitle.examples; + + + Drawing a dashed line + + +]]> + + + This examples draws a line with a 10 and 1 points long line, and + gaps of 5 points inbetween. + + + + + &reftitle.seealso; diff --git a/reference/ps/functions/ps-shading-pattern.xml b/reference/ps/functions/ps-shading-pattern.xml index ba5ad2ca70..75d1865d3d 100644 --- a/reference/ps/functions/ps-shading-pattern.xml +++ b/reference/ps/functions/ps-shading-pattern.xml @@ -1,5 +1,5 @@ - + @@ -22,6 +22,40 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + shadingid + + + The identifier of a shading previously createed with + ps_shading. + + + + + optlist + + + This argument is not currently used. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-shading.xml b/reference/ps/functions/ps-shading.xml index 930c25b38e..681f9d2c5f 100644 --- a/reference/ps/functions/ps-shading.xml +++ b/reference/ps/functions/ps-shading.xml @@ -1,5 +1,5 @@ - + @@ -41,7 +41,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -63,7 +64,9 @@ The coordinates x0, y0, x1, y1 are the start and - end point of the shading. + end point of the shading. If the type of shading is + radial the two points are the middle points of + a starting and ending circle. diff --git a/reference/ps/functions/ps-shfill.xml b/reference/ps/functions/ps-shfill.xml index 45deb7b7b0..65e377fc25 100644 --- a/reference/ps/functions/ps-shfill.xml +++ b/reference/ps/functions/ps-shfill.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,35 @@ Fills an area with a shading, which has to be created before with - ps_shading. + ps_shading. This is an alternative way to creating + a pattern from a shading ps_shading_pattern and using + the pattern as the filling color. + + + + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + shadingid + + + The identifier of a shading previously createed with + ps_shading. + + + + diff --git a/reference/ps/functions/ps-show-boxed.xml b/reference/ps/functions/ps-show-boxed.xml index 64fef8dc1c..421f4848fc 100644 --- a/reference/ps/functions/ps-show-boxed.xml +++ b/reference/ps/functions/ps-show-boxed.xml @@ -1,5 +1,5 @@ - + @@ -27,24 +27,108 @@ Tabulators are treated as spaces. - The text will be hyphenated if the parameter "hyphenation" is set to "true" - and the parameter "hyphendict" contains a valid filename for a hyphenation - file. The line spacing is taken from the value "leading". Paragraphs can be - separated by an empty line just like in TeX. If the value "parindent" is + The text will be hyphenated if the parameter + hyphenation is set to true + and the parameter hyphendict contains a valid + filename for a hyphenation + file. The line spacing is taken from the value leading. + Paragraphs can be + separated by an empty line just like in TeX. If the value + parindent is set to value > 0.0 then the first n lines will be indented. The number n - of lines is set by the parameter "numindentlines". In order to prevent - indenting of the first m paragraphs set the value "parindentskip" to a + of lines is set by the parameter numindentlines. + In order to prevent + indenting of the first m paragraphs set the value + parindentskip to a positive number. + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + text + + + The text to be output into the given box. + + + + + left + + + x-coordinate of the lower left corner of the box. + + + + + bottom + + + y-coordinate of the lower left corner of the box. + + + + + width + + + Width of the box. + + + + + height + + + Height of the box. + + + + + hmode + + + The parameter hmode can be "justify", + "fulljustify", "right", "left", or "center". The difference of + "justify" and "fulljustify" just affects the last line of the box. In + fulljustify mode the last line will be left and right justified unless + this is also the last line of paragraph. In justify mode it will always + be left justified. + + + + + feature + + + + + + + + + + Used parameters The output of ps_show_boxed can be configured with several parameters and values which must be set with either ps_set_parameter or ps_set_value. - Beside the parameters and values which affect text output the following + Beside the parameters and values which affect text output, the following parameters and values are evaluated. @@ -195,83 +279,6 @@ - - &reftitle.parameters; - - - - psdoc - - - - - - - - text - - - - - - - - left - - - - - - - - bottom - - - - - - - - width - - - - - - - - height - - - - - - - - hmode - - - The parameter hmode can be "justify", - "fulljustify", "right", "left", or "center". The difference of - "justify" and "fulljustify" just affects the last line of the box. In - fulljustify mode the last line will be left and right justified unless - this is also the last line of paragraph. In justify mode it will always - be left justified. - - - - - feature - - - - - - - - - - &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-show-xy.xml b/reference/ps/functions/ps-show-xy.xml index c5b0aa074f..e33680b433 100644 --- a/reference/ps/functions/ps-show-xy.xml +++ b/reference/ps/functions/ps-show-xy.xml @@ -1,5 +1,5 @@ - + @@ -21,6 +21,47 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + text + + + The text to be output. + + + + + x + + + x-coordinate of the lower left corner of the box surounding the text. + + + + + y + + + y-coordinate of the lower left corner of the box surounding the text. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-show.xml b/reference/ps/functions/ps-show.xml index c47c839d28..bdaca666ed 100644 --- a/reference/ps/functions/ps-show.xml +++ b/reference/ps/functions/ps-show.xml @@ -1,5 +1,5 @@ - + @@ -15,8 +15,11 @@ stringtext - Output a text at the current text position. The function will issue an - error if no font was set before with ps_setfont. + Output a text at the current text position. The text position can be set + by storing the x and y coordinates into the values textx + and texty with the function + ps_set_value. The function will issue an + error if a font was not set before with ps_setfont. ps_show evaluates the following parameters and values @@ -82,6 +85,31 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + text + + + The text to be output. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-string-geometry.xml b/reference/ps/functions/ps-string-geometry.xml index da337b1aef..2a856ae7c5 100644 --- a/reference/ps/functions/ps-string-geometry.xml +++ b/reference/ps/functions/ps-string-geometry.xml @@ -1,5 +1,5 @@ - + @@ -18,10 +18,54 @@ This function is similar to ps_stringwidth but returns - an array of dimensions. + an array of dimensions containing the width, ascender, and descender + of the text. + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + text + + + The text for which the geometry is to be calculated. + + + + + fontid + + + The identifier of the font to be used. If not font is specified + the current font will be used. + + + + + size + + + The size of the font. If no size is specified the current size + is used. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-stringwidth.xml b/reference/ps/functions/ps-stringwidth.xml index 3b22265c37..7f032cee99 100644 --- a/reference/ps/functions/ps-stringwidth.xml +++ b/reference/ps/functions/ps-stringwidth.xml @@ -1,5 +1,5 @@ - + @@ -25,6 +25,49 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + text + + + The text for which the geometry is to be calculated. + + + + + fontid + + + The identifier of the font to be used. If not font is specified + the current font will be used. + + + + + size + + + The size of the font. If no size is specified the current size + is used. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-stroke.xml b/reference/ps/functions/ps-stroke.xml index 581a471519..be8a51f81c 100644 --- a/reference/ps/functions/ps-stroke.xml +++ b/reference/ps/functions/ps-stroke.xml @@ -1,5 +1,5 @@ - + @@ -19,6 +19,23 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-symbol-name.xml b/reference/ps/functions/ps-symbol-name.xml index 7c1e311f5e..ccfd5fe9fb 100644 --- a/reference/ps/functions/ps-symbol-name.xml +++ b/reference/ps/functions/ps-symbol-name.xml @@ -1,5 +1,5 @@ - + @@ -29,7 +29,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -46,7 +47,8 @@ fontid - + The identifier of the font to be used. If not font is specified + the current font will be used. diff --git a/reference/ps/functions/ps-symbol-width.xml b/reference/ps/functions/ps-symbol-width.xml index 9686f355bb..6ab2677a88 100644 --- a/reference/ps/functions/ps-symbol-width.xml +++ b/reference/ps/functions/ps-symbol-width.xml @@ -1,5 +1,5 @@ - + @@ -31,7 +31,8 @@ psdoc - + Resource identifier of the postscript file + as returned by ps_new. @@ -39,8 +40,7 @@ ord - The parameter ord is the position of the glyph - in the font encoding vector. + The position of the glyph in the font encoding vector. @@ -48,7 +48,8 @@ fontid - Its description + The identifier of the font to be used. If not font is specified + the current font will be used. @@ -56,7 +57,8 @@ size - + The size of the font to be used. If not size is specified + the current font size will be used. diff --git a/reference/ps/functions/ps-symbol.xml b/reference/ps/functions/ps-symbol.xml index d5ce170124..1a7ed33e5c 100644 --- a/reference/ps/functions/ps-symbol.xml +++ b/reference/ps/functions/ps-symbol.xml @@ -1,5 +1,5 @@ - + @@ -21,6 +21,31 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + ord + + + The position of the glyph in the font encoding vector. + + + + + + + &reftitle.returnvalues; diff --git a/reference/ps/functions/ps-translate.xml b/reference/ps/functions/ps-translate.xml index ae141ae522..8474f8aeca 100644 --- a/reference/ps/functions/ps-translate.xml +++ b/reference/ps/functions/ps-translate.xml @@ -1,5 +1,5 @@ - + @@ -20,6 +20,39 @@ + + &reftitle.parameters; + + + + psdoc + + + Resource identifier of the postscript file + as returned by ps_new. + + + + + x + + + x-coordinate of the origin of the translated coordinate system. + + + + + y + + + y-coordinate of the origin of the translated coordinate system. + + + + + + + &reftitle.returnvalues; @@ -27,6 +60,77 @@ + + &reftitle.examples; + + + Translation of the coordinate system + + + +]]> + + The above example demonstrates two possible ways to place + a graphic (in this case just a rectangle) at any position on the page, + while the graphic itself uses its own coordinate system. The trick is + to change the origin of the current coordinate system before drawing + the rectangle. The translation has to undone after the graphic has + been drawn. + + + On the second page a slighty different and more elegant approach is + applied. Instead of undoing the translation with a second call of + ps_translate the graphics context is saved before + modifying the coordinate system and restored after drawing the rectangle. + + + + + &reftitle.seealso;