CVS update: phpdoc/functions

Date: Thursday June 17, 1999 @ 14:26 Author: steinm Update of /repository/phpdoc/functions In directory php:/tmp/cvs-serv910/functions Modified Files: pdf.sgml Log Message: - several corrections - more examples Index: phpdoc/functions/pdf.sgml diff -u phpdoc/functions/pdf.sgml:1.2 phpdoc/functions/pdf.sgml:1.3 --- phpdoc/functions/pdf.sgml:1.2 Tue Jun 15 16:59:47 1999 +++ phpdoc/functions/pdf.sgml Thu Jun 17 14:26:24 1999 @@ -7,27 +7,28 @@ <simpara> You can use the pdf functions in PHP to create pdf files if you - have the PDF library (available at <ulink url = - "http://www.ifconnection.de/~tm/">http://www.ifconnection.de/~tm/</ulink>) - by Thomas Merz. Please consult the excelent documentation for - pdflib shipped with the source distribution of pdflib or available - at <ulink url = - "http://www.ifconnection.de/~tm/software/pdflib/PDFlib-0.6.pdf"> - http://www.ifconnection.de/~tm/software/pdflib/PDFlib-0.6.pdf</ulink>. - As long as this documentation is not complete the pdflib - documentation should be your first choice. The functions in pdflib - and the php3 module have the same name. The parameters are also - identical. You should also understand some of the concepts of pdf - to efficiently use this module. + have the PDF library by Thomas Merz (available at <ulink url = + "http://www.ifconnection.de/~tm/">http://www.ifconnection.de/~tm/</ulink>). + Please consult the excelent documentation for + pdflib shipped with the source distribution of pdflib or available at + <ulink url="http://www.ifconnection.de/~tm/software/pdflib/PDFlib-0.6.pdf">http://www.ifconnection.de/~tm/software/pdflib/PDFlib-0.6.pdf</ulink>. + It provides a very good overview of what pdflib is capable to perform. + Most of the functions in pdflib + and the PHP module have the same name. The parameters are also + identical. You should also understand some of the concepts of PDF + or Postscript to efficiently use this module. + All lenght and coordinates are measured in Postscript points. + One inch are 72 Postscript points. <simpara> - There is another php module for pdf document creation based on + There is another PHP module for pdf document creation based on FastIO's ClibPDF. It has a slightly different API. Check the - php documentation for more info. + PHP documentation for more info. <simpara> - Currently two version of pdflib are support: 0.6 and 2.0. It is - recommended to use the newer version since it fixes some problems + Currently two version of pdflib are supported: 0.6 and 2.0. It is + recommended to use the newer version since it has more features and + fixes some problems which required a patch for the old version. Unfortunately, the changes of the pdflib API in 2.0 have been so severe that even some PHP functions had to be altered. Here is a list of changes: @@ -43,7 +44,7 @@ <function>pdf_set_info_subject</function> and <function>pdf_set_info_keywords</function> do not take the info structure as the first parameter but the pdf document. This - also means that the pdf document must be open before these functions + also means that the pdf document must be opened before these functions can be called. </simpara> </listitem> @@ -60,18 +61,19 @@ The pdf module introduces two new types of variables (if pdflib 2.0 is used it is only one new type). They are called <parameter>pdfdoc</parameter> and <parameter>pdfinfo</parameter> - (<parameter>pdfinfo</parameter> is not existent if use pdflib 2.0 - is used. - <parameter>pdfdoc</parameter> is a pointer to a PDF document and + (<parameter>pdfinfo</parameter> is not existent if pdflib 2.0 is used. + <parameter>pdfdoc</parameter> is a pointer to a pdf document and almost all functions need it as its first parameter. <parameter>pdfinfo</parameter> contains meta data about the PDF - document. + document. It has to be set before <function>pdf_open</function> is + called. <simpara> In order to output text into a PDF document you will need to provide - the afm file for each font. By default these afm files are searched + the afm file for each font. Afm files contain font metrics for a + Postscript font. By default these afm files are searched for in a directory named 'fonts' relative to the directory where the - php3 script is located. (Again, this was true for pdflib 0.6, newer + PHP script is located. (Again, this was true for pdflib 0.6, newer versions do not not neccessarily need the afm files.) <simpara> @@ -80,7 +82,7 @@ example should help to get started. It uses the PHP functions for pdflib 0.6. It creates the file test.pdf with one page. The page contains the text "Times-Roman" in an - outlined 30pt font. The text also is underlined. + outlined 30pt font. The text is also underlined. <example> <title>Creating a PDF document with pdflib 0.6</title> <programlisting> @@ -103,14 +105,15 @@ pdf_stroke($pdf); PDF_end_page($pdf); PDF_close($pdf); -echo "&lt;A HREF=gettest.php3>finished&lt;/A>"; +fclose($fp); +echo "&lt;A HREF=getpdf.php3>finished&lt;/A>"; ?> </programlisting> </example> <para> - The php3 file gettext.php3 just outputs the pdf document. + The PHP script getpdf.php3 just outputs the pdf document. <informalexample> <programlisting> @@ -132,7 +135,7 @@ $fp = fopen("test.pdf", "w"); $pdf = PDF_open($fp); pdf_set_info_author($pdf, "Uwe Steinmann"); -PDF_set_info_title($pdf, "Test for PHP3 wrapper of PDFlib 0.6"); +PDF_set_info_title($pdf, "Test for PHP3 wrapper of PDFlib 2.0"); PDF_set_info_author($pdf, "Name of Author"); pdf_set_info_creator($pdf, "See Author"); pdf_set_info_subject($pdf, "Testing"); @@ -146,17 +149,19 @@ pdf_stroke($pdf); PDF_end_page($pdf); PDF_close($pdf); -echo "&lt;A HREF=gettest.php3>finished&lt;/A>"; +fclose($fp); +echo "&lt;A HREF=getpdf.php3>finished&lt;/A>"; ?> </programlisting> <para> - The php3 file gettext.php3 is the same as above. + The PHP script getpdf.php3 is the same as above. </example> The pdflib distribution contains a more complex example which creates a serious of pages with an analog clock. This example - converted into php using pdflib 2.0 looks as the following (you - can see the same example in the documentation for the clibpdf module): + converted into PHP using pdflib 2.0 looks as the following (you + can see the same example in the documentation for the + <link linkend="ref.cpdf">clibpdf module)</link>: <example> <title>pdfclock example from pdflib 2.0 distribution</title> @@ -247,17 +252,14 @@ $pdf = pdf_close($pdf); fclose($fp); -echo "&lt;A HREF=gettest.php3?filename=".$pdffilename.">finished&lt;/A>"; +echo "&lt;A HREF=getpdf.php3?filename=".$pdffilename.">finished&lt;/A>"; ?> </programlisting> <para> - The php3 file gettext.php3 just outputs the pdf document. + The PHP script getpdf.php3 just outputs the pdf document. <programlisting> &lt;?php -if($filename) - $fp = fopen($filename, "r"); -else - $fp = fopen("test.pdf", "r"); +$fp = fopen($filename, "r"); header("Content-type: application/pdf"); fpassthru($fp); fclose($fp); @@ -278,9 +280,10 @@ <paramdef>string <parameter>filename</parameter></paramdef> </funcsynopsis> <para> - The <function>PDF_get_info</function> function will return a - default info structure for the pdf document. It can be filled - with appropriate information like the author, subject etc. + The <function>PDF_get_info</function> function returns a + default info structure for the pdf document. It should be filled + with appropriate information like the author, subject etc. of + the document. <note><simpara> This functions is not available if pdflib 2.0 support is activated. @@ -288,6 +291,9 @@ <para> See also <function>PDF_set_info_creator</function>, + <function>PDF_set_info_author</function>, + <function>PDF_set_info_keywords</function>, + <function>PDF_set_info_title</function>, <function>PDF_set_info_subject</function>. </refsect1> </refentry> @@ -324,6 +330,8 @@ <para> See also <function>PDF_get_info</function>, + <function>PDF_set_info_keywords</function>, + <function>PDF_set_info_title</function>, <function>PDF_set_info_subject</function>. </refsect1> @@ -345,8 +353,8 @@ The <function>PDF_set_info_title</function> function sets the title of a pdf document. It has to be called after <function>PDF_get_info</function> and before - <function>PDF_open</function>. Calling it after <function>PDF_open</function> - will have no effect on the document. + <function>PDF_open</function>. Calling it after + <function>PDF_open</function> will have no effect on the document. <note><simpara> This function is not part of the pdf library. @@ -361,7 +369,10 @@ <para> See also <function>PDF_get_info</function>, - <function>PDF_set_info_xxxxx</function>. + <function>PDF_set_info_creator</function>, + <function>PDF_set_info_author</function>, + <function>PDF_set_info_keywords</function>, + <function>PDF_set_info_subject</function>. </refsect1> </refentry> @@ -382,8 +393,8 @@ The <function>PDF_set_info_subject</function> function sets the subject of a pdf document. It has to be called after <function>PDF_get_info</function> and before - <function>PDF_open</function>. Calling it after <function>PDF_open</function> - will have no effect on the document. + <function>PDF_open</function>. Calling it after + <function>PDF_open</function> will have no effect on the document. <note><simpara> This function is not part of the pdf library. @@ -398,7 +409,10 @@ <para> See also <function>PDF_get_info</function>, - <function>PDF_set_info_xxxxx</function>. + <function>PDF_set_info_creator</function>, + <function>PDF_set_info_author</function>, + <function>PDF_set_info_title</function>, + <function>PDF_set_info_keywords</function>. </refsect1> </refentry> @@ -435,7 +449,10 @@ <para> See also <function>PDF_get_info</function>, - <function>PDF_set_info_xxxxx</function>. + <function>PDF_set_info_creator</function>, + <function>PDF_set_info_author</function>, + <function>PDF_set_info_title</function>, + <function>PDF_set_info_subject</function>. </refsect1> </refentry> @@ -472,7 +489,10 @@ <para> See also <function>PDF_get_info</function>, - <function>PDF_set_info_xxxxx</function>. + <function>PDF_set_info_creator</function>, + <function>PDF_set_info_keywords</function>, + <function>PDF_set_info_title</function>, + <function>PDF_set_info_subject</function>. </refsect1> </refentry> @@ -494,7 +514,7 @@ a new pdf document. The corresponding file has to be opened with <function>fopen</function> and the file descriptor passed as argument <parameter>file</parameter>. <parameter>info</parameter> - is the an info structure that has to be created with + is the info structure that has to be created with <function>pdf_get_info</function>. The info structure will be deleted within this function. @@ -504,13 +524,14 @@ </simpara></note> <note><simpara> - This function does not require the second parameter if pdflib 2.0 support + This function does not allow the second parameter if pdflib 2.0 support is activated. </simpara></note> <para> See also <function>fopen</function>, - <function>PDF_get_info</function>. + <function>PDF_get_info</function>, + <function>PDF_close</function>. </refsect1> </refentry> @@ -518,7 +539,7 @@ <refentry id="function.pdf-close"> <refnamediv> <refname>PDF_close</refname> - <refpurpose>Closes the pdf document</refpurpose> + <refpurpose>Closes a pdf document</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -531,7 +552,7 @@ <note><simpara>Due to an unclean implementation of the pdflib 0.6 the internal closing of the document also closes the file. This should - not be done because pdflib didn't open the file, but expects an + not be done because pdflib did not open the file, but expects an already open file when <function>PDF_open</function> is called. Consequently it shouldn't close the file. In order to fix this just take out line 190 of the file p_basic.c in the pdflib 0.6 @@ -554,7 +575,7 @@ <refentry id="function.pdf-begin-page"> <refnamediv> <refname>PDF_begin_page</refname> - <refpurpose>Starts page</refpurpose> + <refpurpose>Starts new page</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -578,7 +599,7 @@ <refentry id="function.pdf-end-page"> <refnamediv> <refname>PDF_end_page</refname> - <refpurpose>Ends page</refpurpose> + <refpurpose>Ends a page</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -588,9 +609,10 @@ </funcsynopsis> <para> The <function>PDF_end_page</function> function ends a page. + Once a page is ended it cannot be modified anymore. <para> - See also <function>PDF_end_page</function>. + See also <function>PDF_begin_page</function>. </refsect1> </refentry> @@ -609,11 +631,13 @@ </funcsynopsis> <para> The <function>PDF_show</function> function outputs the - string in <parameter>text</parameter> at the current position. + string <parameter>text</parameter> at the current position + using the current font. <para> See also <function>PDF_show_xy</function>, - <function>PDF_set_text_pos</function>. + <function>PDF_set_text_pos</function>, + <function>PDF_set_font</function>. </refsect1> </refentry> @@ -621,7 +645,7 @@ <refentry id="function.pdf-show-xy"> <refnamediv> <refname>PDF_show_xy</refname> - <refpurpose>Output text at position</refpurpose> + <refpurpose>Output text at given position</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -634,8 +658,8 @@ </funcsynopsis> <para> The <function>PDF_show_xy</function> function outputs the - string in <parameter>text</parameter> at position with - coordinates (<parameter>x-koor</parameter>, <parameter>y-koor</parameter>). + string <parameter>text</parameter> at position + (<parameter>x-koor</parameter>, <parameter>y-koor</parameter>). <para> See also <function>PDF_show</function>. @@ -646,7 +670,7 @@ <refentry id="function.pdf-set-font"> <refnamediv> <refname>PDF_set_font</refname> - <refpurpose>Select the current font face and size</refpurpose> + <refpurpose>Selects a font face and size</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -658,13 +682,14 @@ <paramdef>int <parameter>encoding</parameter></paramdef> </funcsynopsis> <para> - The <function>PDF_set_font</function> function sets the the + The <function>PDF_set_font</function> function sets the current font face, font size and encoding. You will need to provide the Adobe Font Metrics (afm-files) for the font in the font path (default is ./fonts). The last parameter <parameter>encoding</parameter> can take the following values: 0 = builtin, 1 = pdfdoc, 2 = macroman, 3 = macexpert, 4 = winansi. An encoding greater than 4 and less than 0 will default to winansi. + winansi is often a good choice. <note><simpara> This function does not need the afm files for winansi encoding if @@ -751,7 +776,7 @@ </funcsynopsis> <para> The <function>PDF_set_text_rise</function> function sets the - text rising to <parameter>value</parameter> units. + text rising to <parameter>value</parameter> points. </refsect1> </refentry> @@ -770,7 +795,7 @@ <para> The <function>PDF_set_text_matrix</function> function sets a matrix which describes a transformation applied on the current - text font. + text font. The matrix has to passed as an array with six elements. </refsect1> </refentry> @@ -814,7 +839,7 @@ spacing between characters. <para> See also <function>PDF_set_word_spacing</function>, - <function>PDF_set_text_leading</function>. + <function>PDF_set_leading</function>. </refsect1> </refentry> @@ -837,7 +862,7 @@ <para> See also <function>PDF_set_char_spacing</function>, - <function>PDF_set_text_leading</function>. + <function>PDF_set_leading</function>. </refsect1> </refentry> @@ -845,7 +870,7 @@ <refentry id="function.pdf-continue-text"> <refnamediv> <refname>PDF_continue_text</refname> - <refpurpose>Output text in next line</refpurpose> + <refpurpose>Outputs text in next line</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -857,10 +882,12 @@ <para> The <function>PDF_continue_text</function> function outputs the string in <parameter>text</parameter> in the next line. + The distance between the lines can be set with + <function>PDF_set_leading</function>. <para> See also <function>PDF_show_xy</function>, - <function>PDF_set_text_leading</function>, + <function>PDF_set_leading</function>, <function>PDF_set_text_pos</function>. </refsect1> @@ -869,7 +896,7 @@ <refentry id="function.pdf-stringwidth"> <refnamediv> <refname>PDF_stringwidth</refname> - <refpurpose>Returns width of text in current font</refpurpose> + <refpurpose>Returns width of text using current font</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -892,7 +919,7 @@ <refentry id="function.pdf-save"> <refnamediv> <refname>PDF_save</refname> - <refpurpose>Saves current enviroment</refpurpose> + <refpurpose>Saves the current environment</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -902,9 +929,10 @@ </funcsynopsis> <para> The <function>PDF_save</function> function saves the current - enviroment. It works like the postscript command gsave. Very + environment. It works like the postscript command gsave. Very useful if you want to translate or rotate an object without effecting - other objects. + other objects. <function>PDF_save</function> should always be + followed by <function>PDF_restore</function>. <para> See also <function>PDF_restore</function>. @@ -915,7 +943,7 @@ <refentry id="function.pdf-restore"> <refnamediv> <refname>PDF_restore</refname> - <refpurpose>Restores formerly saved enviroment</refpurpose> + <refpurpose>Restores formerly saved environment</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -925,13 +953,13 @@ </funcsynopsis> <para> The <function>PDF_restore</function> function restores the - enviroment saved with <function>PDF_save</function>. It works + environment saved with <function>PDF_save</function>. It works like the postscript command grestore. Very useful if you want to translate or rotate an object without effecting other objects. <example> - <title>PDF_get_info</title> + <title>Save and Restore</title> <programlisting> &lt;?php PDF_save($pdf); // do all kinds of rotations, transformations, ... @@ -960,7 +988,24 @@ <para> The <function>PDF_translate</function> function set the origin of coordinate system to the point (<parameter>x-koor</parameter>, - <parameter>y-koor</parameter>). + <parameter>y-koor</parameter>). The following example draws + a line from (0, 0) to (200, 200) relative to the initial coordinate + system. You have to set the current point after + <function>PDF_translate</function> and before you start drawing + more objects. + + <example> + <title>Translation</title> + <programlisting> +&lt;?php PDF_moveto($pdf, 0, 0); +PDF_lineto($pdf, 100, 100); +PDF_stroke($pdf); +PDF_translate($pdf, 100, 100); +PDF_moveto($pdf, 0, 0); +PDF_lineto($pdf, 100, 100); +PDF_stroke($pdf); +?> +</programlisting></example> </refsect1> </refentry> @@ -980,7 +1025,18 @@ </funcsynopsis> <para> The <function>PDF_scale</function> function set the scaling factor - in both directions. + in both directions. The following example scales x and y direction + by 72. The following line will therefore be drawn one inch in both + directions. + + <example> + <title>Scaling</title> + <programlisting> +&lt;?php PDF_scale($pdf, 72.0, 72.0); +PDF_lineto($pdf, 1, 1); +PDF_stroke($pdf); +?> +</programlisting></example> </refsect1> </refentry> @@ -1045,7 +1101,7 @@ <refentry id="function.pdf-setlinecap"> <refnamediv> <refname>PDF_setlinecap</refname> - <refpurpose>Sets linecap aparameter</refpurpose> + <refpurpose>Sets linecap parameter</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1114,8 +1170,8 @@ </funcsynopsis> <para> The <function>PDF_setdash</function> function set the dash pattern - <parameter>white</parameter> white units and <parameter>black</parameter> - black units. If both are 0 a solid line is set. + <parameter>white</parameter> white points and <parameter>black</parameter> + black points. If both are 0 a solid line is set. </refsect1> </refentry> @@ -1168,7 +1224,8 @@ <para> See also <function>PDF_moveto</function>, - <function>PDF_lineto</function>. + <function>PDF_lineto</function>, + <function>PDF_stroke</function>. </refsect1> </refentry> @@ -1193,7 +1250,8 @@ <para> See also <function>PDF_moveto</function>, - <function>PDF_curveto</function>. + <function>PDF_curveto</function>, + <function>PDF_stroke</function>. </refsect1> </refentry> @@ -1201,7 +1259,7 @@ <refentry id="function.pdf-circle"> <refnamediv> <refname>PDF_circle</refname> - <refpurpose>Draw a circle</refpurpose> + <refpurpose>Draws a circle</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1219,7 +1277,8 @@ and radius <parameter>radius</parameter>. <para> - See also <function>PDF_arc</function>. + See also <function>PDF_arc</function>, + <function>PDF_stroke</function>. </refsect1> </refentry> @@ -1249,7 +1308,8 @@ <parameter>end</parameter>. <para> - See also <function>PDF_circle</function>. + See also <function>PDF_circle</function>, + <function>PDF_stroke</function>. </refsect1> </refentry> @@ -1257,7 +1317,7 @@ <refentry id="function.pdf-rect"> <refnamediv> <refname>PDF_rect</refname> - <refpurpose>Draw a rectangle</refpurpose> + <refpurpose>Draws a rectangle</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1276,13 +1336,15 @@ This width is set to <parameter>widgth</parameter>. This height is set to <parameter>height</parameter>. + <para> + See also <function>PDF_stroke</function>. </refsect1> </refentry> <refentry id="function.pdf-closepath"> <refnamediv> <refname>PDF_closepath</refname> - <refpurpose>Close path</refpurpose> + <refpurpose>Closes path</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1292,7 +1354,10 @@ </funcsynopsis> <para> The <function>PDF_closepath</function> function closes the - current path. + current path. This means, it draws a line from current point to + the point where the first line was started. Many functions like + <function>PDF_moveto</function>, <function>PDF_circle</function> + and <function>PDF_rect</function> start a new path. </refsect1> </refentry> @@ -1300,7 +1365,7 @@ <refentry id="function.pdf-stroke"> <refnamediv> <refname>PDF_stroke</refname> - <refpurpose>Draw line along path</refpurpose> + <refpurpose>Draws line along path</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1310,7 +1375,8 @@ </funcsynopsis> <para> The <function>PDF_stroke</function> function draws a line along - current path. + current path. The current path is the sum of all line drawing. + Without this function the line would not be drawn. <para> See also <function>PDF_closepath</function>, @@ -1322,7 +1388,7 @@ <refentry id="function.pdf-closepath-stroke"> <refnamediv> <refname>PDF_closepath_stroke</refname> - <refpurpose>Close path and draw line along path</refpurpose> + <refpurpose>Closes path and draws line along path</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1345,7 +1411,7 @@ <refentry id="function.pdf-fill"> <refnamediv> <refname>PDF_fill</refname> - <refpurpose>Fill current path</refpurpose> + <refpurpose>Fills current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1371,7 +1437,7 @@ <refentry id="function.pdf-fill-stroke"> <refnamediv> <refname>PDF_fill_stroke</refname> - <refpurpose>Fill and stroke current path</refpurpose> + <refpurpose>Fills and strokes current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1398,7 +1464,7 @@ <refentry id="function.pdf-closepath-fill-stroke"> <refnamediv> <refname>PDF_closepath_fill_stroke</refname> - <refpurpose>Close, fill and stroke current path</refpurpose> + <refpurpose>Closes, fills and strokes current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1701,7 +1767,7 @@ <refentry id="function.pdf-open-memory-image"> <refnamediv> <refname>PDF_open_memory_image</refname> - <refpurpose>Opens an image created with php3 image functions</refpurpose> + <refpurpose>Opens an image created with PHP's image functions</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1712,7 +1778,7 @@ </funcsynopsis> <para> The <function>PDF_open_memory_image</function> function takes - an image created with the php3 image functions and makes it available + an image created with the PHP's image functions and makes it available for the pdf document. <para> See also <function>PDF_close_image</function>,