/golst

Produce readable source code listings for Go source files.

Primary LanguageGoISC LicenseISC

golst

golst is a Go command line tool for generating readable program listings. It was inspired by Luke Gorries' post "Readable Programs" and, in particular, his pbook example.

Listings that are written to a file are written as <file.go>.<format>; for example, producing listings for listing.go:

  • markdown -> listing.go.md
  • HTML -> listing.go.html
  • PDF -> listing.go.pdf

Examples

  • To produce an HTML listing for listing.go:

      golst -o html listing.go

    This will produce listing.go.html, which is a standalone page. The template for this page is contained in the html.go source file, and is taken from my site tyrfingr.

  • To produce a PDF listing for pandoc.go:

      golst -o pdf pandoc.go

    Similar to the previous example, this will produce the PDF file pandoc.go.pdf.

  • To produce a markdown listing for html.go and have this printed to standard output:

      golst html.go

    Or, alternatively,

      golst -o - html.go

  • You can produce listings for multiple files at the same time:

      golst -o pdf *.go

    If you ran this on the golst directory, you would have listing.go.pdf, html.go.pdf, and pandoc.go.pdf.

Supported Output Formats

Standalone listings are generated; the following formats (selected with the -o flag) are supported:

  • html - generate HTML listing
  • latex - uses pandoc to convert the markdown to a LaTeX listing.
  • md - generate markdown listing
  • pdf - uses pandoc to convert the markdown to a PDF listing.
  • tex - rudimentary pure-Go TeX listing.

Dependencies

  • golst uses blackfriday for producing HTML from the listing. This will automatically be pulled in by go get.

  • pandoc is required for conversion to PDF.

License

golst is released under an ISC license. For details, see LICENSE in the source repository.