diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/document.md | 254 | ||||
| -rw-r--r-- | doc/go.awk | 19 | ||||
| -rw-r--r-- | doc/html.txt | 68 |
3 files changed, 341 insertions, 0 deletions
diff --git a/doc/document.md b/doc/document.md new file mode 100644 index 0000000..16ca686 --- /dev/null +++ b/doc/document.md @@ -0,0 +1,254 @@ +# GoFPDF document generator + +[![MIT licensed][badge-mit]][license] +[![Report][badge-report]][report] +[![GoDoc][badge-doc]][godoc] + +![][logo] + +Package gofpdf implements a PDF document generator with high level support for +text, drawing and images. + +## 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, TIFF 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 +* Templates +* Barcodes +* Charting facility + +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. In particular, languages that require more than one code +page such as Chinese, Japanese, and Arabic are not currently supported. This is +explained in [issue 109][issue109]. However, support is provided to +automatically translate UTF-8 runes to code page encodings for languages that +have fewer than 256 glyphs. + +## Installation + +To install the package on your system, run + +```shell +go get github.com/jung-kurt/gofpdf +``` + +Later, to receive updates, run + +```shell +go get -u -v github.com/jung-kurt/gofpdf/... +``` + +## Quick Start + +The following Go code generates a simple PDF file. + +```go +pdf := gofpdf.New("P", "mm", "A4", "") +pdf.AddPage() +pdf.SetFont("Arial", "B", 16) +pdf.Cell(40, 10, "Hello, world") +err := pdf.OutputFileAndClose("hello.pdf") +``` + +See the functions in the [fpdf_test.go][fpdf-test] 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][fpdf-site] library written in PHP (despite the caveat in the +introduction to [Effective Go][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][fpdf-test] for some helper routines, for example +`exampleFilename()` and `summary()`. + +Example PDFs can be compared with reference copies in order to verify that they +have been generated as expected. This comparison will be performed if a PDF +with the same name as the example PDF is placed in the gofpdf/pdf/reference +directory and if the third argument to `ComparePDFFiles()` in +internal/example/example.go is true. (By default it is false.) The routine that +summarizes an example will look for this file and, if found, will call +`ComparePDFFiles()` to check the example PDF for equality with its reference PDF. +If differences exist between the two files they will be printed to standard +output and the test will fail. If the reference file is missing, the comparison +is considered to succeed. In order to successfully compare two PDFs, the +placement of internal resources must be consistent and the internal creation +timestamps must be the same. To do this, the methods `SetCatalogSort()` and +`SetCreationDate()` need to be called for both files. This is done automatically +for all examples. + +## 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. + +```shell +./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 [Google Fonts][gfont] and [DejaVu Fonts][dfont]. + +## Related Packages + +The [draw2d][draw2d-site] package is a two dimensional vector graphics library that +can generate output in different forms. It uses gofpdf for its document +production mode. + +## Contributing Changes + +gofpdf is a global community effort and you are invited to make it even better. +If you have implemented a new feature or corrected a problem, please consider +contributing your change to the project. A contribution that does not directly +pertain to the core functionality of gofpdf should be placed in its own +directory directly beneath the `contrib` directory. + +Here are guidelines for making submissions. Your change should + +* be compatible with the MIT License +* be properly documented +* be formatted with `go fmt` +* include an example in [fpdf_test.go][test] if appropriate +* conform to the standards of [golint][lint] and +[go vet][vet], that is, `golint .` and +`go vet .` should not generate any warnings +* not diminish [test coverage][coverage] + +[Pull requests][pr] are the preferred means of accepting your changes. + +## License + +gofpdf is released under the MIT License. It is copyrighted by Kurt Jung and +the contributors acknowledged below. + +## Acknowledgments + +This package's code and documentation are closely derived from the [FPDF][fpdf-site] +library created by Olivier Plathey, and a number of font and image resources +are copied directly from it. Bruno Michel has provided valuable assistance with +the code. 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, enhanced fill modes, and has helped +greatly with package presentation and tests. Templating is adapted by Marcus +Downing from the FPDF_Tpl library created by Jan Slabon and Setasign. Jelmer +Snoeck contributed packages that generate a variety of barcodes and help with +registering images on the web. Jelmer Snoek and Guillermo Pascual augmented the +basic HTML functionality with aligned text. Kent Quirk implemented +backwards-compatible support for reading DPI from images that support it, and +for setting DPI manually and then having it properly taken into account when +calculating image size. Paulo Coutinho provided support for static embedded +fonts. Dan Meyers added support for embedded JavaScript. David Fish added a +generic alias-replacement function to enable, among other things, table of +contents functionality. Andy Bakun identified and corrected a problem in which +the internal catalogs were not sorted stably. Paul Montag added encoding and +decoding functionality for templates, including images that are embedded in +templates; this allows templates to be stored independently of gofpdf. Paul +also added support for page boxes used in printing PDF documents. Wojciech +Matusiak added supported for word spacing. + +## 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. + + +[badge-author]: https://img.shields.io/badge/author-Kurt_Jung-blue.svg +[badge-doc]: https://img.shields.io/badge/godoc-GoFPDF-blue.svg +[badge-github]: https://img.shields.io/badge/project-Git_Hub-blue.svg +[badge-mit]: https://img.shields.io/badge/license-MIT-blue.svg +[badge-report]: https://goreportcard.com/badge/github.com/jung-kurt/gofpdf +[badge-status]: https://travis-ci.org/jung-kurt/gofpdf.svg?branch=master +[coverage]: https://blog.golang.org/cover +[dfont]: http://dejavu-fonts.org/ +[draw2d-site]: https://github.com/llgcode/draw2d +[effective-go]: https://golang.org/doc/effective_go.html +[fpdf-site]: http://www.fpdf.org/ +[fpdf-test]: https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go +[gfont]: https://fonts.google.com/ +[github]: https://github.com/jung-kurt/gofpdf +[godoc]: https://godoc.org/github.com/jung-kurt/gofpdf +[issue109]: https://github.com/jung-kurt/gofpdf/issues/109 +[jung]: https://github.com/jung-kurt/ +[license]: https://raw.githubusercontent.com/jung-kurt/gofpdf/master/LICENSE +[lint]: https://github.com/golang/lint +[logo]: https://github.com/jung-kurt/gofpdf/raw/master/image/logo_gofpdf.jpg?raw=true +[pr]: https://help.github.com/articles/using-pull-requests/ +[report]: https://goreportcard.com/report/github.com/jung-kurt/gofpdf +[status]: https://travis-ci.org/jung-kurt/gofpdf +[test]: https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go +[vet]: https://golang.org/cmd/vet/ diff --git a/doc/go.awk b/doc/go.awk new file mode 100644 index 0000000..a325362 --- /dev/null +++ b/doc/go.awk @@ -0,0 +1,19 @@ +BEGIN { + show = 0 + print "/*" +} + +/^\-/ { + trim = 1 + print "" +} + +/^Package/ { show = 1 } + +!NF { trim = 0 } + +trim { sub("^ +", "", $0) } + +show { print $0 } + +END { print "*/\npackage gofpdf" } diff --git a/doc/html.txt b/doc/html.txt new file mode 100644 index 0000000..7a89bb1 --- /dev/null +++ b/doc/html.txt @@ -0,0 +1,68 @@ +<!doctype html> + +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width initial-scale=1 maximum-scale=1 minimum-scale=1 user-scalable=0" /> + <title>GoFPDF Document Generator</title> + <style> + body { + max-width: 800px; + font-family: sans-serif; + padding: 1em; + } + + img { + max-width: 800px; + } + + h1, + h2, + h3 { + color: #345; + } + + .syntax { + display: block; + white-space: pre; + font-family: monospace; + background-color: #efe; + border: 1px solid #474; + margin: 1em 0; + padding: 0.25em 1.5em; + } + + .warning { + background-color: #ffd; + border: 1px solid #665; + margin: 1em 0; + padding: 0 1em; + } + + .key { + color: #131; + font-weight: bold; + } + + .subkey { + font-style: italic; + } + + pre { + margin: 1.5em 0; + background-color: #eee; + padding: 1em; + overflow-x: scroll; + } +$if(highlighting-css)$ +$highlighting-css$ +$endif$ + </style> +</head> + +<body> +$body$ +</body> + +</html> |