name | description |
---|---|
podium |
POD parser and tool |
You can try Podium in your browser at https://pod.deno.dev/.
This is a parser and tool for Plain Old Documentation (POD).
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.
$ wget https://pod.deno.dev/podium.lua
$ chmod +x podium.lua
To use Podium, you can either use the WebAPI, the command line interface, or the application programming interface.
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
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
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 backend = podium.html -- or markdown, latex, vimdoc
print(podium.process(backend, 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.
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)
-- read file as string
local inputString = io.open('path/to/file.pod'):read('*a')
-- process the string
local outputString = podium.process(podium.html, inputString)
-- write the string to file
io.open('path/to/file.html', 'w'):write(outputString)
Podium consists of the three components:
process
converts a string into another string using aPodiumBackend
instance.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:
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)
print(podium.process(backend, inputString)) -- process returns output string
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)
print(podium.process(backend, inputString)) -- process returns output string
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)
print(podium.process(backend, inputString)) -- process returns output string
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)
print(podium.process(html, inputString)) -- process returns output string
Podium is written in Lua, but you can use it in JavaScript as well.
import {LuaFactory} from 'npm:wasmoon@latest';
const luaFactory = new LuaFactory();
const lua = await luaFactory.createEngine();
const code = Deno.readTextFileSync('./lua/podium.lua').replace("#!/usr/bin/env lua", "")
const pod = await lua.doString(code);
// Arguments: backend name, node name, modifier function
pod.PodiumBackend.registerSimpleDataParagraph("html", "red", (arg) => {
return `<span style="color: red">${red}<span>`
})
// Arguments: backend name, input string
// Returns: output string
pod.process("html", "...")
Licensed under MIT License.
Copyright (c) 2022 TANIGUCHI Masaya