# gmi2pdf

Convert gemtext/plaintext file (local or Gemini resource) to PDF file

gmi2pdf was created by Vi Grey <vi@vigrey.com>


## Description

gmi2pdf takes a gemtext file or a gemini link and converts the content
to a PDF file.  For converting local files, gmi2pdf assumes the file is
a gemtext file.  For converting content from a link, both plaintext and
gemtext files are accepted to be converted to a pdf file.  Optionally,
a TLS client signed certificate file and TLS client certificate private
key can be specified for gemini requests.

PDF files are created using groff.  If ghostscript is installed,
ghostscript will be used to shrink the filesize of the resulting PDF
file.

Only ASCII characters are currently supported.  An optional flag can be
used to turn unicode characters into squares rather than ommitting them
entirely.


## Dependencies

### OS Dependencies

- Linux

This program might work on quite a few flavors of *BSD and possibly
macOS as well, but they have not been tested on those platforms. This
program also might work on Windows via WSL, but has not been tested on
that platform.

### Build Dependencies

- go >= 1.20

### Use Dependencies

- groff

### Optional Use Dependencies

- ghostscript

## Build

To build gmi2pdf, use the following command in the root directory of
this repository

```
$ make
```

The resulting binary file will be located at `build/bin/gmi2pdf


## Usage

```
$ gm2pdf -h
Usage: gmi2pdf [OPTIONS]...

Options:
  -2, --2column           Create 2-column PDF
  -a, --address <URL>     URL to gemini capsule page to turn into PDF
                          Cannot be used with --in flag
  -c, --tlscert <path>    Path to TLS client signed certificate file
  -d, --debug             Print ms macro troff/groff output to STDOUT
      --excludeheader     Do not include headers on PDF
      --excludefooter     Do not include footers on PDF
  -h, --help              Print Help (this message) and exit
  -i, --in <path>         Path to gemtext file to turn into PDF.
                          Cannot be used with --address flag
  -k, --tlskey <path>     Path to TLS client certificate private key
                          file
  -o, --out <path>        Path of where PDF file will be written
  -q, --query <content>   Query to send to gemini capsule with address
  -s, --size <page_size>  PDF page size.  Can be "Letter" (8.5in by
                          11in), "A4" (210mm by 297mm), "Legal" (8.5in
                          by 14in), or "Tabloid" (11in by 17in).
                          Default is "Letter"
  -t, --plaintext         If using --in flag, process the file as
                          a plaintext file
  -u, --unicode           Show unsupported unicode characters as boxes
  -v, --version           Print version and exit

Examples:
  gmi2pdf -a gemini://example.com/comment.gmi \
        -q "Test content" -k /path/to/gemini-ident.key \
        -c /path/to/gemini-ident.crt -o /path/for/comment.pdf
    (This example sends the query "Test content" to
     gemini://example.com/comment.gmi using the TLS client certificate
     and key found at path/to/gemini-ident.key and
     path/to/gemini-ident.csv.  The resulting gemtext file is converted
     into a US letter sized PDF file with headers and footers and and
     stored at /path/for/comment.pdf.  Unsupported unicode characters
     are not included in the PDF file.)
  gmi2pdf -i /path/to/article.gmi \
        -o /path/for/article.pdf -2 -s tabloid --excludefooter \
        --excludeheader -u -d
    (This example converts the gemtext file at /path/to/article.gmi to
     a tabloid sized PDF of 11in by 17in and saves the PDF file to
     /path/for/article.pdf.  The PDF content is 2 columned and the
     header and footer data are not included in the PDF.  Unsupported
     unicode characters are converted to boxes.  After the PDF file is
     created, the ms macro groff/troff data is printed to STDOUT.)
  gmi2pdf -i /path/to/article.txt \
        -o /path/for/article.pdf -s A4 -t
    (This example converts the plaintext file at /path/to/article.txt
     to an A4 sized PDF of 210mm by 297mm and saves the PDF file to
     /path/for/article.pdf.)
```