https://github.com/tani/podium
The documentation tools from POD to Markdown/ HTML/ vimdoc/ LaTeX
https://github.com/tani/podium
Last synced: 2 months ago
JSON representation
The documentation tools from POD to Markdown/ HTML/ vimdoc/ LaTeX
- Host: GitHub
- URL: https://github.com/tani/podium
- Owner: tani
- Created: 2023-05-10T13:35:51.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-12T23:25:04.000Z (10 months ago)
- Last Synced: 2025-04-15T19:09:07.022Z (2 months ago)
- Language: Lua
- Homepage: https://pod.deno.dev
- Size: 148 KB
- Stars: 20
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.pod
Awesome Lists containing this project
README
---
name: podium
description: POD parser and tool
---
=pod
=head1 Podium
=head2 Playground X
You can try Podium in your browser at L.
=head2 Description X
This is a parser and tool for L.
=head2 Features X
POD parser provides a convenient way to write documentation and comes with the
following features:
=over
=item * Easy-to-read syntax
=item * Multiple output formats (HTML, Markdown, LaTeX, Vimdoc)
=item * Command line interface for simple conversion
=item * Extensible for integration into other projects
=back
To get started using POD, download a file and follow
the usage instructions provided in the subsequent sections.
=head2 Installation X
$ wget https://pod.deno.dev/podium.lua
$ chmod +x podium.lua
=head2 Usage X
To use Podium, you can either use the WebAPI, the command line interface, or
the application programming interface.
=head3 WebAPI X
WebAPI is available at L.
$ 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
=head3 Command Line Interface X
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
=head3 Application Programming Interface X
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
=over
=item 1. Create a new C object,
which takes an output format as an argument.
=item 2. Call the C method on the PodiumProcessor object.
=back
To customize the output, see below.
=head2 Customization X
B
-- example.lua
podium = dofile('podium.lua')
-- customize the output
podium.html:registerSimpleFormattingCode('B', function (text)
return '' .. text .. ''
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:
=over
=item * C converts a string into another string using a C instance.
=item * C converts the tree structure into a string.
=item * C represents a node in the tree structure.
=back
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 C instance,
which has four methods for simple customization:
=head3 C X
This method registers a simple formatting code, e.g., C...E>.
C is the name of the formatting code: the single capital letter.
C 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 '' .. text .. ''
end)
print(podium.process(backend, inputString)) -- process returns output string
=head3 C X
This method registers a simple command, e.g., C<=head1 ...>.
C is the name of the command defined in the POD document.
Please do not override C<=begin> and C<=end> commands.
local podium = require('podium')
local inputString = "..."
local backend = podium.html -- or markdown, latex, vimdoc
backend:registerSimpleCommand('head1', function (text)
return '
' .. text .. '
'
end)
print(podium.process(backend, inputString)) -- process returns output string
=head3 C X
This method registers a simple data paragraph, e.g., content between
C<=begin name> and C<=end name> commands.
C 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 '
' .. text .. ''
end)
print(podium.process(backend, inputString)) -- process returns output string
=head3 C X
This method is used to register another simple conversion, e.g., preamble, and
postambles. C is the name of the conversion, e.g., preamble, and
postambles. C 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 ''
end)
:registerSimple('postamble', function (text)
return ''
end)
print(podium.process(html, inputString)) -- process returns output string
=head2 JavaScript API X
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 `${red}`
})
// Arguments: backend name, input string
// Returns: output string
pod.process("html", "...")
=head2 License X
Licensed under MIT License.
Copyright (c) 2022 TANIGUCHI Masaya
=cut