MFB: Upgrade to the new-reference-structure

- Split reference.xml into book.xml, setup.xml and examples.xml
- Moved from reference.xml to book.xml:
  - The intro text (partintro), and link to various pages
- Moved from reference.xml to setup.xml:
  - The rest: requirements, installation, configuration, resources, and hints
- Moved from reference.xml to examples.xml: all the examples
- Added new constants page
- Changed the intro ID from <extname>.intro to intro.<extname>


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248822 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2007-12-23 16:45:59 +00:00
parent 7e6cf93fb5
commit 8a783261cc
5 changed files with 343 additions and 235 deletions

117
reference/pdf/book.xml Normal file
View file

@ -0,0 +1,117 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: utilspec.nontext -->
<!-- Membership: pecl, external -->
<book xml:id="book.pdf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>PDF</title>
<!-- {{{ preface -->
<preface xml:id="intro.pdf">
&reftitle.intro;
<para>
The PDF functions in PHP can create PDF files using the PDFlib
library which was initially created by Thomas Merz and is now
maintained by <link xlink:href="&url.pdf;">PDFlib GmbH</link>.
</para>
<para>
The documentation in this section is only meant to be an overview
of the available functions in the PDFlib library and should not be
considered an exhaustive reference. For the full and detailed
explanation of each function, consult the PDFlib Reference Manual
which is included in all PDFlib packages distributed by PDFlib GmbH.
It provides a very good overview of what PDFlib is capable of doing
and contains the most up-to-date documentation of all functions.
</para>
<para>
For a jump start we urge you to take a look at the programming samples
which are contained in all PDFlib distribution packages. These samples
demonstrate basic text, vector, and graphics output as well as
higher-level functions, such as the PDF import facility (PDI).
</para>
<para>
All of the functions in PDFlib and the PHP module have identical
function names and parameters. Unless configured otherwise, all
lengths and coordinates are measured in PostScript points. There are
generally 72 PostScript points to an inch, but this depends on the
output resolution. Please see the PDFlib Reference Manual
included in the PDFlib distribution for a more thorough explanation
of the coordinate system used.
</para>
<para>
With version 6, PDFlib offers an object-oriented API for PHP 5 in
addition to the function-oriented API for PHP 4. The main difference is
the following:
</para>
<para>
In PHP 4, first a PDF resource has to be retrieved with a function call
like
</para>
<para>
$p = PDF_new().
</para>
<para>
This PDF resource is used as the first parameter in all further function
calls, such as in
</para>
<para>
PDF_begin_document($p, "", "").
</para>
<para>
In PHP 5 however, a PDFlib object is created with
</para>
<para>
$p = new PDFlib().
</para>
<para>
This object offers all PDFlib API functions as methods, e.g. as with
</para>
<para>
$p->begin_document("", "").
</para>
<para>
In addition, exceptions have been introduced in PHP 5 which are
supported by PDFlib 6 and later as well.
</para>
<para>
Please see the <link linkend="pdf.examples">examples</link> below for
more information.
</para>
<note>
<para>
If you're interested in alternative free PDF generators that do not
utilize external PDF libraries, see <link linkend="faq.using.freepdf">
this related FAQ</link>.
</para>
</note>
</preface>
<!-- }}} -->
&reference.pdf.setup;
&reference.pdf.constants;
&reference.pdf.examples;
&reference.pdf.reference;
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,29 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<appendix xml:id="pdf.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&no.constants;
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

121
reference/pdf/examples.xml Normal file
View file

@ -0,0 +1,121 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="pdf.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.examples;
<section xml:id="pdf.examples-basic">
<title>Basic Usage Examples</title>
<para>
Most of the functions are fairly easy to use. The most difficult part
is probably creating your first PDF document. The following
example should help to get you started. It is developed for PHP 4 and
creates the file <filename>hello.pdf</filename> with one page.
It defines some document info field contents, loads the Helvetica-Bold
font and outputs the text "Hello world! (says PHP)".
</para>
<para>
<example>
<title>Hello World example from PDFlib distribution for PHP 4</title>
<programlisting role="php">
<![CDATA[
<?php
$p = PDF_new();
/* open new PDF file; insert a file name to create the PDF on disk */
if (PDF_begin_document($p, "", "") == 0) {
die("Error: " . PDF_get_errmsg($p));
}
PDF_set_info($p, "Creator", "hello.php");
PDF_set_info($p, "Author", "Rainer Schaaf");
PDF_set_info($p, "Title", "Hello world (PHP)!");
PDF_begin_page_ext($p, 595, 842, "");
$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");
PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says PHP)");
PDF_end_page_ext($p, "");
PDF_end_document($p, "");
$buf = PDF_get_buffer($p);
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
PDF_delete($p);
?>
]]>
</programlisting>
</example>
</para>
<para>
The following example comes with the PDFlib distribution for PHP 5.
It uses the new exception handling and object encapsulation features
available in PHP 5. It creates the file <filename>hello.pdf</filename>
with one page. It defines some document info field contents, loads the
Helvetica-Bold font and outputs the text "Hello world! (says PHP)".
</para>
<para>
<example>
<title>Hello World example from PDFlib distribution for PHP 5</title>
<programlisting role="php">
<![CDATA[
<?php
try {
$p = new PDFlib();
/* open new PDF file; insert a file name to create the PDF on disk */
if ($p->begin_document("", "") == 0) {
die("Error: " . $p->get_errmsg());
}
$p->set_info("Creator", "hello.php");
$p->set_info("Author", "Rainer Schaaf");
$p->set_info("Title", "Hello world (PHP)!");
$p->begin_page_ext(595, 842, "");
$font = $p->load_font("Helvetica-Bold", "winansi", "");
$p->setfont($font, 24.0);
$p->set_text_pos(50, 700);
$p->show("Hello world!");
$p->continue_text("(says PHP)");
$p->end_page_ext("");
$p->end_document("");
$buf = $p->get_buffer();
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
}
catch (PDFlibException $e) {
die("PDFlib exception occurred in hello sample:\n" .
"[" . $e->get_errnum() . "] " . $e->get_apiname() . ": " .
$e->get_errmsg() . "\n");
}
catch (Exception $e) {
die($e);
}
$p = 0;
?>
]]>
</programlisting>
</example>
</para>
</section>
</chapter>

View file

@ -1,126 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.28 $ -->
<!-- Purpose: utilspec.nontext -->
<!-- Membership: pecl, external -->
<!-- $Revision: 1.29 $ -->
<reference xml:id="ref.pdf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>PDF &Functions;</title>
<titleabbrev>PDF</titleabbrev>
<partintro>
<section xml:id="pdf.intro">
&reftitle.intro;
<para>
The PDF functions in PHP can create PDF files using the PDFlib
library which was initially created by Thomas Merz and is now
maintained by <link xlink:href="&url.pdf;">PDFlib GmbH</link>.
</para>
<para>
The documentation in this section is only meant to be an overview
of the available functions in the PDFlib library and should not be
considered an exhaustive reference. For the full and detailed
explanation of each function, consult the PDFlib Reference Manual
which is included in all PDFlib packages distributed by PDFlib GmbH.
It provides a very good overview of what PDFlib is capable of doing
and contains the most up-to-date documentation of all functions.
</para>
<para>
For a jump start we urge you to take a look at the programming samples
which are contained in all PDFlib distribution packages. These samples
demonstrate basic text, vector, and graphics output as well as
higher-level functions, such as the PDF import facility (PDI).
</para>
<para>
All of the functions in PDFlib and the PHP module have identical
function names and parameters. Unless configured otherwise, all
lengths and coordinates are measured in PostScript points. There are
generally 72 PostScript points to an inch, but this depends on the
output resolution. Please see the PDFlib Reference Manual
included in the PDFlib distribution for a more thorough explanation
of the coordinate system used.
</para>
<para>
With version 6, PDFlib offers an object-oriented API for PHP 5 in
addition to the function-oriented API for PHP 4. The main difference is
the following:
</para>
<para>
In PHP 4, first a PDF resource has to be retrieved with a function call
like
</para>
<para>
$p = PDF_new().
</para>
<para>
This PDF resource is used as the first parameter in all further function
calls, such as in
</para>
<para>
PDF_begin_document($p, "", "").
</para>
<para>
In PHP 5 however, a PDFlib object is created with
</para>
<para>
$p = new PDFlib().
</para>
<para>
This object offers all PDFlib API functions as methods, e.g. as with
</para>
<para>
$p->begin_document("", "").
</para>
<para>
In addition, exceptions have been introduced in PHP 5 which are
supported by PDFlib 6 and later as well.
</para>
<para>
Please see the <link linkend="pdf.examples">examples</link> below for
more information.
</para>
<note>
<para>
If you're interested in alternative free PDF generators that do not
utilize external PDF libraries, see <link linkend="faq.using.freepdf">
this related FAQ</link>.
</para>
</note>
</section>
<section xml:id="pdf.requirements">
&reftitle.required;
<para>
PDFlib Lite is available as open source. However, the
PDFlib Lite license allows free use only under certain conditions.
PDFlib Lite supports a subset of PDFlib's functionality; please see the
PDFlib web site for details. The full version of PDFlib is available for
download at <link xlink:href="&url.pdf;">&url.pdf;</link>, but requires that
you purchase a license for commercial use.
</para>
</section>
<section xml:id="pdf.oldlibs.hints">
<title>Issues with older versions of PDFlib</title>
<para>
Any version of PHP 4 after March 9, 2000 does not support versions
of PDFlib older than 3.0.
</para>
<para>
PDFlib 4.0 or greater is supported by PHP 4.3.0 and later.
</para>
</section>
&reference.pdf.configure;
<section xml:id="pdf.resources">
&reftitle.resources;
<para>
<function>PDF_new</function> creates a new PDFlib object required by most
PDF functions.
</para>
</section>
<section xml:id="pdf.oldlibs">
<partintro xml:id="pdf.oldlibs">
<title>Remarks about Deprecated PDFlib Functions</title>
<para>
Starting with PHP 4.0.5, the PHP extension for PDFlib is
@ -135,123 +19,6 @@
functions. The documentation in this section indicates old functions as
"Deprecated" and gives the replacement function to be used instead.
</para>
</section>
<section xml:id="pdf.examples">
&reftitle.examples;
<para>
Most of the functions are fairly easy to use. The most difficult part
is probably creating your first PDF document. The following
example should help to get you started. It is developed for PHP 4 and
creates the file <filename>hello.pdf</filename> with one page.
It defines some document info field contents, loads the Helvetica-Bold
font and outputs the text "Hello world! (says PHP)".
</para>
<para>
<example>
<title>Hello World example from PDFlib distribution for PHP 4</title>
<programlisting role="php">
<![CDATA[
<?php
$p = PDF_new();
/* open new PDF file; insert a file name to create the PDF on disk */
if (PDF_begin_document($p, "", "") == 0) {
die("Error: " . PDF_get_errmsg($p));
}
PDF_set_info($p, "Creator", "hello.php");
PDF_set_info($p, "Author", "Rainer Schaaf");
PDF_set_info($p, "Title", "Hello world (PHP)!");
PDF_begin_page_ext($p, 595, 842, "");
$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");
PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says PHP)");
PDF_end_page_ext($p, "");
PDF_end_document($p, "");
$buf = PDF_get_buffer($p);
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
PDF_delete($p);
?>
]]>
</programlisting>
</example>
</para>
<para>
The following example comes with the PDFlib distribution for PHP 5.
It uses the new exception handling and object encapsulation features
available in PHP 5. It creates the file <filename>hello.pdf</filename>
with one page. It defines some document info field contents, loads the
Helvetica-Bold font and outputs the text "Hello world! (says PHP)".
</para>
<para>
<example>
<title>Hello World example from PDFlib distribution for PHP 5</title>
<programlisting role="php">
<![CDATA[
<?php
try {
$p = new PDFlib();
/* open new PDF file; insert a file name to create the PDF on disk */
if ($p->begin_document("", "") == 0) {
die("Error: " . $p->get_errmsg());
}
$p->set_info("Creator", "hello.php");
$p->set_info("Author", "Rainer Schaaf");
$p->set_info("Title", "Hello world (PHP)!");
$p->begin_page_ext(595, 842, "");
$font = $p->load_font("Helvetica-Bold", "winansi", "");
$p->setfont($font, 24.0);
$p->set_text_pos(50, 700);
$p->show("Hello world!");
$p->continue_text("(says PHP)");
$p->end_page_ext("");
$p->end_document("");
$buf = $p->get_buffer();
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
}
catch (PDFlibException $e) {
die("PDFlib exception occurred in hello sample:\n" .
"[" . $e->get_errnum() . "] " . $e->get_apiname() . ": " .
$e->get_errmsg() . "\n");
}
catch (Exception $e) {
die($e);
}
$p = 0;
?>
]]>
</programlisting>
</example>
</para>
</section>
</partintro>
&reference.pdf.entities.functions;

74
reference/pdf/setup.xml Normal file
View file

@ -0,0 +1,74 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="pdf.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="pdf.requirements">
&reftitle.required;
<para>
PDFlib Lite is available as open source. However, the
PDFlib Lite license allows free use only under certain conditions.
PDFlib Lite supports a subset of PDFlib's functionality; please see the
PDFlib web site for details. The full version of PDFlib is available for
download at <link xlink:href="&url.pdf;">&url.pdf;</link>, but requires that
you purchase a license for commercial use.
</para>
<section xml:id="pdf.oldlibs.hints">
<title>Issues with older versions of PDFlib</title>
<para>
Any version of PHP 4 after March 9, 2000 does not support versions
of PDFlib older than 3.0.
</para>
<para>
PDFlib 4.0 or greater is supported by PHP 4.3.0 and later.
</para>
</section>
</section>
<!-- }}} -->
<!-- {{{ Installation -->
&reference.pdf.configure;
<!-- }}} -->
<!-- {{{ Configuration -->
<section xml:id="pdf.configuration">
&reftitle.runtime;
&no.config;
</section>
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="pdf.resources">
&reftitle.resources;
<para>
<function>PDF_new</function> creates a new PDFlib object required by most
PDF functions.
</para>
</section>
<!-- }}} -->
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->