summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md156
1 files changed, 155 insertions, 1 deletions
diff --git a/README.md b/README.md
index bca3d04..9c526d9 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,160 @@
Package gofpdf implements a PDF document generator with high level support for
text, drawing and images.
-See the [documentation][1] for more details.
+##Features
+• Choice of measurement unit, page format and margins
+
+• Page header and footer management
+
+• Automatic page breaks, line breaks, and text justification
+
+• Inclusion of JPEG, PNG, GIF and basic path-only SVG images
+
+• Colors, gradients and alpha channel transparency
+
+• Outline bookmarks
+
+• Internal and external links
+
+• TrueType, Type1 and encoding support
+
+• Page compression
+
+• Lines, Bézier curves, arcs, and ellipses
+
+• Rotation, scaling, skewing, translation, and mirroring
+
+• Clipping
+
+• Document protection
+
+• Layers
+
+gofpdf has no dependencies other than the Go standard library. All tests pass
+on Linux, Mac and Windows platforms. Like FPDF version 1.7, from which gofpdf
+is derived, this package does not yet support UTF-8 fonts. However, support is
+provided to translate UTF-8 runes to code page encodings.
+
+##Acknowledgments
+This package's code and documentation are closely derived from the FPDF library
+created by Olivier Plathey, and a number of font and image resources are copied
+directly from it. Drawing support is adapted from the FPDF geometric figures
+script by David Hernández Sanz. Transparency support is adapted from the FPDF
+transparency script by Martin Hall-May. Support for gradients and clipping is
+adapted from FPDF scripts by Andreas Würmser. Support for outline bookmarks is
+adapted from Olivier Plathey by Manuel Cornes. Layer support is adapted from
+Olivier Plathey. Support for transformations is adapted from the FPDF
+transformation script by Moritz Wagner and Andreas Würmser. PDF protection is
+adapted from the work of Klemen Vodopivec for the FPDF product. Lawrence
+Kesteloot provided code to allow an image's extent to be determined prior to
+placement. Support for vertical alignment within a cell was provided by Stefan
+Schroeder. Ivan Daniluk generalized the font and image loading code to use the
+Reader interface while maintaining backward compatibility. Anthony Starks
+provided code for the Polygon function. Robert Lillack provided the Beziergon
+function and corrected some naming issues with the internal curve function.
+Claudio Felber provided implementations for dashed line drawing and generalized
+font loading. Stani Michiels provided support for multi-segment path drawing
+with smooth line joins, line join styles and enhanced fill modes. Bruno Michel
+has provided valuable assistance with the code.
+
+The FPDF website is http://www.fpdf.org/.
+
+##License
+gofpdf is released under the MIT License. It is copyrighted by Kurt Jung and
+the contributors acknowledged above.
+
+##Installation
+To install the package on your system, run
+
+```
+go get github.com/jung-kurt/gofpdf
+```
+
+Later, to receive updates, run
+
+```
+go get -u github.com/jung-kurt/gofpdf
+```
+
+##Quick Start
+The following Go code generates a simple PDF and writes it to standard output.
+
+```
+pdf := gofpdf.New("P", "mm", "A4", "")
+pdf.AddPage()
+pdf.SetFont("Arial", "B", 16)
+pdf.Cell(40, 10, "Hello, world")
+pdf.Output(os.Stdout)
+```
+
+See the functions in the fpdf_test.go file (shown as examples in this
+documentation) for more advanced PDF examples.
+
+##Errors
+If an error occurs in an Fpdf method, an internal error field is set. After
+this occurs, Fpdf method calls typically return without performing any
+operations and the error state is retained. This error management scheme
+facilitates PDF generation since individual method calls do not need to be
+examined for failure; it is generally sufficient to wait until after Output()
+is called. For the same reason, if an error occurs in the calling application
+during PDF generation, it may be desirable for the application to transfer the
+error to the Fpdf instance by calling the SetError() method or the SetErrorf()
+method. At any time during the life cycle of the Fpdf instance, the error state
+can be determined with a call to Ok() or Err(). The error itself can be
+retrieved with a call to Error().
+
+##Conversion Notes
+This package is a relatively straightforward translation from the original FPDF
+library written in PHP (despite the caveat in the introduction to Effective
+Go). The API names have been retained even though the Go idiom would suggest
+otherwise (for example, pdf.GetX() is used rather than simply pdf.X()). The
+similarity of the two libraries makes the original FPDF website a good source
+of information. It includes a forum and FAQ.
+
+However, some internal changes have been made. Page content is built up using
+buffers (of type bytes.Buffer) rather than repeated string concatenation.
+Errors are handled as explained above rather than panicking. Output is
+generated through an interface of type io.Writer or io.WriteCloser. A number of
+the original PHP methods behave differently based on the type of the arguments
+that are passed to them; in these cases additional methods have been exported
+to provide similar functionality. Font definition files are produced in JSON
+rather than PHP.
+
+##Example PDFs
+A side effect of running "go test" is the production of a number of example
+PDFs. These can be found in the gofpdf/pdf directory after the tests complete.
+
+Please note that these examples run in the context of a test. In order run an
+example as a standalone application, you'll need to examine fpdf_test.go for
+some helper routines, for example exampleFilename and summary.
+
+##Nonstandard Fonts
+Nothing special is required to use the standard PDF fonts (courier, helvetica,
+times, zapfdingbats) in your documents other than calling SetFont().
+
+In order to use a different TrueType or Type1 font, you will need to generate a
+font definition file and, if the font will be embedded into PDFs, a compressed
+version of the font file. This is done by calling the MakeFont function or
+using the included makefont command line utility. To create the utility, cd
+into the makefont subdirectory and run "go build". This will produce a
+standalone executable named makefont. Select the appropriate encoding file from
+the font subdirectory and run the command as in the following example.
+
+```
+./makefont --embed --enc=../font/cp1252.map --dst=../font ../font/calligra.ttf
+```
+
+In your PDF generation code, call AddFont() to load the font and, as with the
+standard fonts, SetFont() to begin using it. Most examples, including the
+package example, demonstrate this method. Good sources of free, open-source
+fonts include http://www.google.com/fonts/ and http://dejavu-fonts.org/.
+
+##Roadmap
+• Handle UTF-8 source text natively. Until then, automatic translation of
+UTF-8 runes to code page bytes is provided.
+
+• Improve test coverage as reported by the coverage tool.
+
+
[1]: http://godoc.org/github.com/jung-kurt/gofpdf