Use Pandoc to generate README and doc.go

5 files changed, 286 insertions, 107 deletions

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/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/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>