diff options
| -rw-r--r-- | Makefile | 29 | ||||
| -rw-r--r-- | README.md | 366 | ||||
| -rw-r--r-- | doc.go | 333 | ||||
| -rw-r--r-- | doc/doc.lua | 100 | ||||
| -rw-r--r-- | doc/document.md (renamed from document.md) | 16 | ||||
| -rw-r--r-- | doc/ftr.html | 3 | ||||
| -rw-r--r-- | doc/go.awk | 19 | ||||
| -rw-r--r-- | doc/html.txt (renamed from doc/hdr.html) | 17 |
8 files changed, 407 insertions, 476 deletions
@@ -1,9 +1,8 @@ -doc : README.md doc.go doc/index.html.ok +all : documentation -test : - go test -v +documentation : doc/index.html doc.go README.md -cov : +cov : all go test -v -coverprofile=coverage && go tool cover -html=coverage -o=coverage.html check : @@ -11,19 +10,19 @@ check : go vet -all . gofmt -s -l . -%.html.ok : %.html - tidy -quiet -output /dev/null $< - touch $@ +README.md : doc/document.md + pandoc --read=markdown --write=gfm < $< > $@ -doc/body.md README.md doc.go : document.md - lua doc/doc.lua - gofmt -s -w doc.go +doc/index.html : doc/document.md doc/html.txt + pandoc --read=markdown --write=html --template=doc/html.txt \ + --metadata pagetitle="GoFPDF Document Generator" < $< > $@ -doc/index.html : doc/hdr.html doc/body.html doc/ftr.html - cat doc/hdr.html doc/body.html doc/ftr.html > $@ +doc.go : doc/document.md doc/go.awk + pandoc --read=markdown --write=plain $< | awk -f doc/go.awk > $@ + gofmt -s -w $@ -doc/body.html : doc/body.md - markdown -f +links,+image,+smarty,+ext,+divquote -o $@ $< +build : + go build -v clean : - rm -f coverage.html coverage doc/*.ok doc/body.md README.md doc.go doc/index.html doc/body.html + rm -f coverage.html coverage doc/index.html doc.go README.md @@ -1,55 +1,57 @@ # GoFPDF document generator -[![MIT licensed][badge-mit]][license] -[![Report][badge-report]][report] -[![GoDoc][badge-doc]][godoc] +[](https://raw.githubusercontent.com/jung-kurt/gofpdf/master/LICENSE) +[](https://goreportcard.com/report/github.com/jung-kurt/gofpdf) +[](https://godoc.org/github.com/jung-kurt/gofpdf) - + -Package gofpdf implements a PDF document generator with high level support for -text, drawing and images. +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. + - 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](https://github.com/jung-kurt/gofpdf/issues/109). 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 +``` shell go get github.com/jung-kurt/gofpdf ``` Later, to receive updates, run -```shell +``` shell go get -u -v github.com/jung-kurt/gofpdf/... ``` @@ -57,7 +59,7 @@ go get -u -v github.com/jung-kurt/gofpdf/... The following Go code generates a simple PDF file. -```go +``` go pdf := gofpdf.New("P", "mm", "A4", "") pdf.AddPage() pdf.SetFont("Arial", "B", 16) @@ -66,189 +68,181 @@ 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. +[fpdf\_test.go](https://github.com/jung-kurt/gofpdf/blob/master/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()`. +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. +This package is a relatively straightforward translation from the +original [FPDF](http://www.fpdf.org/) library written in PHP (despite +the caveat in the introduction to [Effective +Go](https://golang.org/doc/effective_go.html)). 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. +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](https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go) +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()`. +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. +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 +``` 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]. +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](https://fonts.google.com/) and [DejaVu +Fonts](http://dejavu-fonts.org/). ## 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. +The [draw2d](https://github.com/llgcode/draw2d) 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. +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] + - be compatible with the MIT License + - be properly documented + - be formatted with `go fmt` + - include an example in + [fpdf\_test.go](https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go) + if appropriate + - conform to the standards of [golint](https://github.com/golang/lint) + and [go vet](https://golang.org/cmd/vet/), that is, `golint .` and + `go vet .` should not generate any warnings + - not diminish [test coverage](https://blog.golang.org/cover) -[Pull requests][pr] are the preferred means of accepting your changes. +[Pull requests](https://help.github.com/articles/using-pull-requests/) +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. +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. +This package’s code and documentation are closely derived from the +[FPDF](http://www.fpdf.org/) 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 -[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/
\ No newline at end of file + - 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,239 +1,260 @@ /* -Package gofpdf implements a PDF document generator with high level support for -text, drawing and images. +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 +- Choice of measurement unit, page format and margins + +- Page header and footer management -• Automatic page breaks, line breaks, and text justification +- Automatic page breaks, line breaks, and text justification -• Inclusion of JPEG, PNG, GIF, TIFF and basic path-only SVG images +- Inclusion of JPEG, PNG, GIF, TIFF and basic path-only SVG images -• Colors, gradients and alpha channel transparency +- Colors, gradients and alpha channel transparency -• Outline bookmarks +- Outline bookmarks -• Internal and external links +- Internal and external links -• TrueType, Type1 and encoding support +- TrueType, Type1 and encoding support -• Page compression +- Page compression -• Lines, Bézier curves, arcs, and ellipses +- Lines, Bézier curves, arcs, and ellipses -• Rotation, scaling, skewing, translation, and mirroring +- Rotation, scaling, skewing, translation, and mirroring -• Clipping +- Clipping -• Document protection +- Document protection -• Layers +- Layers -• Templates +- Templates -• Barcodes +- Barcodes -• Charting facility +- Charting facility -gofpdf has no dependencies other than the Go standard library. All tests pass -on Linux, Mac and Windows platforms. +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. However, support is +provided to automatically translate UTF-8 runes to code page encodings +for languages that have fewer than 256 glyphs. -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. 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 - go get github.com/jung-kurt/gofpdf + go get github.com/jung-kurt/gofpdf Later, to receive updates, run - go get -u -v github.com/jung-kurt/gofpdf/... + go get -u -v github.com/jung-kurt/gofpdf/... + Quick Start The following Go code generates a simple PDF file. - pdf := gofpdf.New("P", "mm", "A4", "") - pdf.AddPage() - pdf.SetFont("Arial", "B", 16) - pdf.Cell(40, 10, "Hello, world") - err := pdf.OutputFileAndClose("hello.pdf") + 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 file (shown as examples in this +documentation) for more advanced PDF examples. -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(). +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. +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(). - -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. +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(). + +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(). +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. +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 + ./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 and DejaVu Fonts. -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 and DejaVu Fonts. Related Packages -The draw2d package is a two dimensional vector graphics library that -can generate output in different forms. It uses gofpdf for its document +The draw2d 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. +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 compatible with the MIT License -• be formatted with go fmt +- be properly documented -• include an example in fpdf_test.go if appropriate +- be formatted with go fmt -• conform to the standards of golint and -go vet, that is, golint . and +- include an example in fpdf_test.go if appropriate + +- conform to the standards of golint and go vet, that is, golint . and go vet . should not generate any warnings -• not diminish test coverage +- not diminish test coverage Pull requests 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. +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 -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. +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. 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. +Roadmap -• Improve test coverage as reported by the coverage tool. +- 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. */ package gofpdf diff --git a/doc/doc.lua b/doc/doc.lua deleted file mode 100644 index dbe87c1..0000000 --- a/doc/doc.lua +++ /dev/null @@ -1,100 +0,0 @@ --- This script reads a single page of Markdown-like documentation and generates --- output in three different forms: gofmt, git-flavored markdown, and --- standard markdown. - -local gsub, match, len, find, concat, insert = -string.gsub, string.match, string.len, string.find, table.concat, table.insert - -local function write(filestr, str) - local f = io.open(filestr, 'w+') - if f then - f:write(str) - f:close() - end -end - -local function codeblock(tbl, mode) - local newtbl = {} - local incode = false - local pos1, pos2, prefix, syntax - for j, str in ipairs(tbl) do - prefix, syntax = match(str, '^(```)(%a*)') - if prefix and len(syntax) > 0 then - incode = true - if mode == 'r' then - insert(newtbl, str) - end - elseif prefix then - incode = false - if mode == 'r' then - insert(newtbl, str) - end - else - if incode and mode ~= 'r' then - str = '\t' .. str - end - insert(newtbl, str) - end - end - return newtbl -end - -local function markdownwrite(tbl, filestr) - tbl = codeblock(tbl, 'm') - local str = concat(tbl, '\n') - write(filestr, str) -end - -local function readmewrite(tbl, filestr) - tbl = codeblock(tbl, 'r') - local str = concat(tbl, '\n') - str = gsub(str, '\n%> ', '\n') - -- str = gsub(str, '%b<>', '') - write(filestr, str) -end - -local function godocwrite(tbl, filestr) - tbl = codeblock(tbl, 'g') - for j, str in ipairs(tbl) do - str = gsub(str, '^#+ *', '') - tbl[j] = gsub(str, '^* ', '\n• ') - end - local str = concat(tbl, '\n') - str = gsub(str, '\n\n\n+', '\n\n') - str = gsub(str, '\n%> ', '\n') - str = gsub(str, '`', '') - str = gsub(str, '/%*', '\x01') - str = gsub(str, '%*', '') - str = gsub(str, '\x01', '\x2f*') - -- str = gsub(str, '%b<>', '') - -- replace [foo][bar] with foo - str = gsub(str, '%[(%C-)%]%[%C-%]', '%1') - str = '/*\n' .. str .. '\n*/\npackage gofpdf\n' - write(filestr, str) -end - -local godoc, markdown, readme = {}, {}, {} -local modeg, modem, moder - -for str in io.lines('document.md') do - local mode = string.match(str, '^~(%a*)~$') - if mode then - modeg = find(mode, 'g') ~= nil - moder = find(mode, 'r') ~= nil - modem = find(mode, 'm') ~= nil - else - if modeg then - insert(godoc, str) - end - if modem then - insert(markdown, str) - end - if moder then - insert(readme, str) - end - end -end - -markdownwrite(markdown, 'doc/body.md') -godocwrite(godoc, 'doc.go') -readmewrite(readme, 'README.md') diff --git a/document.md b/doc/document.md index d0f79cb..16ca686 100644 --- a/document.md +++ b/doc/document.md @@ -1,18 +1,11 @@ -~rm~ # GoFPDF document generator -~m~ -[![Git Hub repository][badge-github]][github] -[![Kurt Jung][badge-author]][jung] -~rm~ [![MIT licensed][badge-mit]][license] [![Report][badge-report]][report] [![GoDoc][badge-doc]][godoc] -~rm~ - +![][logo] -~rgm~ Package gofpdf implements a PDF document generator with high level support for text, drawing and images. @@ -72,9 +65,8 @@ 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. +See the functions in the [fpdf_test.go][fpdf-test] file (shown as examples in +this documentation) for more advanced PDF examples. ## Errors @@ -235,7 +227,6 @@ UTF-8 runes to code page bytes is provided. * Improve test coverage as reported by the coverage tool. -~mr~ [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 @@ -255,6 +246,7 @@ UTF-8 runes to code page bytes is provided. [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 diff --git a/doc/ftr.html b/doc/ftr.html deleted file mode 100644 index 47fc456..0000000 --- a/doc/ftr.html +++ /dev/null @@ -1,3 +0,0 @@ - </body> - -</html> 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/hdr.html b/doc/html.txt index 161ec47..7a89bb1 100644 --- a/doc/hdr.html +++ b/doc/html.txt @@ -1,10 +1,11 @@ <!doctype html> -<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>CGI for Caddy</title> + <title>GoFPDF Document Generator</title> <style> body { max-width: 800px; @@ -36,11 +37,12 @@ background-color: #ffd; border: 1px solid #665; margin: 1em 0; - padding: 0.25em 1.5em; + padding: 0 1em; } .key { - color: #474; + color: #131; + font-weight: bold; } .subkey { @@ -53,7 +55,14 @@ padding: 1em; overflow-x: scroll; } +$if(highlighting-css)$ +$highlighting-css$ +$endif$ </style> </head> <body> +$body$ +</body> + +</html> |