name	podium
description	POD parser and tool

Podium

Playground

You can try Podium in your browser at https://pod.deno.dev/.

Description

This is a parser and tool for Plain Old Documentation (POD).

Features

POD parser provides a convenient way to write documentation and comes with the following features:

• Easy-to-read syntax

• Multiple output formats (HTML, Markdown, LaTeX, Vimdoc)

• Command line interface for simple conversion

• Extensible for integration into other projects

To get started using POD, download a file and follow the usage instructions provided in the subsequent sections.

Installation

$ wget https://pod.deno.dev/podium.lua
$ chmod +x podium.lua

Usage

To use Podium, you can either use the WebAPI, the command line interface, or the application programming interface.

WebAPI

WebAPI is available at https://pod.deno.dev/.

$ curl --data-binary @path/to/file.pod https://pod.deno.dev/markdown
$ curl --data-binary `$(cat path/to/file.pod)` https://pod.deno.dev/html
$ cat path/to/file.pod | curl --data-binary @- https://pod.deno.dev/latex

Command Line Interface

To run the command line interface, you need to install Lua.

$ podium.lua markdown path/to/file.pod path/to/file.md   # write markdown
$ podium.lua latex    path/to/file.pod path/to/file.tex  # write latex
$ podium.lua vimdoc   path/to/file.pod path/to/file.txt  # write vimdoc
$ podium.lua html     path/to/file.pod path/to/file.html # write html

$ podium.lua html path/to/file.pod > path/to/file.html # wirte html to stdout
$ podium.lua html < path/to/file.pod > path/to/file.html # write html to stdout, read pod from stdin

Application Programming Interface

If you want to use Podium in your own project, you can use the application programming interface (API) to convert POD to HTML, Markdown, LaTeX, or Vimdoc.

local podium = require('podium')
local inputString = "..."
local outputFormat = podium.html -- or markdown, latex, vimdoc
local processor = podium.PodiumProcessor.new(outputFormat)
print(processor:process(inputString)) -- process returns output string

1. Create a new PodiumProcessor object, which takes an output format as an argument.

2. Call the process method on the PodiumProcessor object.

To customize the output, see below.

Customization

Example:

-- example.lua
podium = dofile('podium.lua')

-- customize the output
podium.html:registerSimpleFormattingCode('B', function (text)
  return '<b style="font-weight: bold">' .. text .. '</b>'
end)

-- create a new processor
local processor = podium.PodiumProcessor.new(podium.html)

-- read file as string
local inputString = io.open('path/to/file.pod'):read('*a')

-- process the string
local outputString = processor:process(inputString)

-- write the string to file
io.open('path/to/file.html', 'w'):write(outputString)

Podium consists of the three components:

• PodiumProcessor parses POD documents into a tree structure.

• PodiumBackend converts the tree structure into a string.

• PodiumElement represents a node in the tree structure.

Please be relaxed, you don't need to know the details of the tree structure. You just need to arrange the simple string-to-string conversion.

You can customize the output by tweaking PodiumBackend instance, which has four methods for simple customization:

registerSimpleFormattingCode(self, name, fun)

This method registers a simple formatting code, e.g., B<...>. name is the name of the formatting code: the single capital letter. fun is a function that takes a string and returns a string.

local podium = require('podium')
local inputString = "..."
local backend = podium.html -- or markdown, latex, vimdoc
backend:registerSimpleFormattingCode('B', function (text)
  return '<b style="font-weight: bold">' .. text .. '</b>'
end)
local processor = podium.PodiumProcessor.new(backend)
print(processor:process(inputString)) -- process returns output string

registerSimpleCommand(self, name, fun)

This method registers a simple command, e.g., =head1 .... name is the name of the command defined in the POD document. Please do not override =begin and =end commands.

local podium = require('podium')
local inputString = "..."
local backend = podium.html -- or markdown, latex, vimdoc
backend:registerSimpleCommand('head1', function (text)
  return '<h1 style="font-weight: bold">' .. text .. '</h1>'
end)
local processor = podium.PodiumProcessor.new(backend)
print(processor:process(inputString)) -- process returns output string

registerSimpleDataParagraph(self, name, fun)

This method registers a simple data paragraph, e.g., content between =begin name and =end name commands. name is the name of the data paragraph, e.g., html or markdown.

local podium = require('podium')
local inputString = "..."
local backend = podium.html -- or markdown, latex, vimdoc
backend:registerSimpleDataParagraph('html', function (text)
  return '<div>' .. text .. '</div>'
end)
local processor = podium.PodiumProcessor.new(backend)
print(processor:process(inputString)) -- process returns output string

registerSimple(self, name, fun)

This method is used to register another simple conversion, e.g., preamble, and postambles. name is the name of the conversion, e.g., preamble, and postambles. fun is a function that takes a string and returns a string. The function takes the entire input string as an argument for preamble and postambles.

local podium = require('podium')
local inputString = "..."
local backend = podium.html -- or markdown, latex, vimdoc
backend
  :registerSimple('preamble', function (text)
    return '<html><body>'
  end)
  :registerSimple('postamble', function (text)
    return '</body></html>'
  end)
local processor = podium.PodiumProcessor.new(backend)
print(processor:process(inputString)) -- process returns output string

License

Licensed under MIT License.

Copyright (c) 2022 TANIGUCHI Masaya