lilydjwg/2bbcode

A set of custom Pandoc writers for converting to BBCode.

2bbcode

A set of custom Pandoc writers for converting to BBCode.

---

• Introduction
  • About Pandoc
  • About BBCode
• System Requirements
• Linux Usage
  • 2bbcode
  • 2bbcode_phpbb
• Windows Usage
  • 2bbcode
  • 2bbcode_phpbb
• Pandoc Setup
  • Windows
    • Pandoc MSI Installer
    • Pandoc via Chocolatey
    • Pandoc Standalone
  • Pandoc Supported Input Formats

Introduction

2bbcode is a project hosting custom pandoc writers, written in Lua, which allow to convert to BBCode any input format supported by pandoc.

Since pandoc ships with a built-in Lua interpreter, using 2bbcode wrtiers doesn’t require installing Lua on the system.

There are several 2bbcode writers in this project, addressing different BBCode flavors:

• 2bbcode.lua – the original 2bbcode writer by @lilydjwg, targeting the BBCode used by FluxBB.
• bbcode_phpbb.lua – a fork of 2bbcode.lua by @tajmone, targeting the BBCode used by phpBB.
• bbcode_hubzilla.lua – a fork of 2bbcode_phpbb.lua by @slobinger, targeting the BBCode used by Hubzilla.
• bbcode_steam.lua – writer for steam flavour bbcode by @0x00002a.

About Pandoc

• Pandoc website | User’s Guide
• Pandoc’s GitHub repo
• Pandoc download page
• Pandoc entry at Wikipedia

Pandoc is a cross-platform FOSS command line tool for converting documents from one format to another. It natively supports more than 20 input formats and over 40 output formats, and can be extended to work with custom input (reader) and outupt (writer) formats through external scripts – likes the custom BBCode writers in this project.

Pandoc is written in Haskell, and precompiled binary releases for Windows, Mac OS X and Linux are available for download.

Pandoc was originally created by John MacFarlane, a philosophy professor at the University of California, Berkeley, and is now maintained collaboratively on GitHub.

About BBCode

• BBCode manual at PHP.net
• BBCode.org (website dedicate to BBCode resources)
• phpBB’s BBCode guide
• BBCode entry at Wikipedia

BBCode (Bulletin Board Code) is a lightweight markup language used by many message boards to format posts. From Wikipedia:

BBCode was introduced in 1998 by the messageboard software Ultimate Bulletin Board (UBB) implemented in Perl. In 2000 BBCode was used in phpBB – an internet forum system written in PHP. vBulletin also uses BBCode.

BBCode tags work in a similar way to HTML tags, but square brackets are employed instead of angle brackets, and no paragraph tag is needed:

Here comes a [b]bold word[/b].

BBCode has fewer tags than HTML, intended to cover simple formatting cases.

Since different implementations of BBCode employ different subsets of tags, there are different flavors of BBCode, and while the most common tags should work across all BBCode implementations, advanced formatting tags might not.

System Requirements

Just pandoc:

• Pandoc

For more information, see Pandoc Setup.

Linux Usage

2bbcode

Required 2bbcode Linux files:

• bbcode.lua
• 2bbcode

./2bbcode FORMAT <input >output

FORMAT defaults to markdown_github. Use pandoc --list-input-formats to list acceptable formats.

2bbcode_phpbb

Required 2bbcode_phpbb Linux files:

• bbcode_phpbb.lua
• 2bbcode_phpbb

./2bbcode_phpbb FORMAT <input >output

Same as with 2bbcode, except for scripts names.

Windows Usage

If you want to use 2bbcode globally, put all the required *.lua and *.bat files in a same folder which is on the system %PATH%.

2bbcode

Required 2bbcode Windows files:

• bbcode.lua
• 2bbcode.bat
• gfm2bbcode.bat

1. Using 2bbcode.bat via command line:

   2bbcode filename.ext
   

   creates filename.bbcode.

   Pandoc will guess input format from input file’s extension. This batch script allows conversion from any pandoc supported input format. For markdown input files, it will default to pandoc’s extended Markdown.

2. Using gfm2bbcode.bat via command line:

   gfm2bbcode filename.md
   

   This will convert the GitHub-Flavored (no hard-linebreaks) input markdown file to filename.bbcode. This batch script invokes pandoc with the following settings:

   --smart --wrap=none --normalize -f markdown_github-hard_line_breaks
   

   … which is most likely what you’re looking for when working with GitHub related markdown files.

3. Using 2bbcode.bat and gfm2bbcode.bat from Windows File Explorer:

   Just drag’n’drop input file over 2bbcode.bat or gfm2bbcode.bat, a converted *.bbcode file will be created in the same folder as input file.

2bbcode_phpbb

Required 2bbcode_phpbb Windows files:

• bbcode_phpbb.lua
• 2bbcode_phpbb.bat
• gfm2bbcode_phpbb.bat

Use is the same as with 2bbcode, except for scripts names.

Pandoc Setup

Windows

You have different choices for setting up pandoc:

1. Use pandoc’s msi installer
2. Install via Chocolatey
3. Use pandoc executable in standalone mode

The advised choice is #2 – install via Chocolatey!

Pandoc MSI Installer

Pandoc for Windows ships with an msi installer.

When asked, choose “install pandoc for current user” (best choice).

Pandoc via Chocolatey

Since Pandoc doesn’t (can’t) check for updates, the best method of installation is via Chocolatey (or ChocolateyGUI):

• Pandoc package at Chocolatey.org

Chocolatey handles silent installation and updates in the background (using default options), and helps you keeping pandoc always updated to the latest release.

Pandoc Standalone

If you prefer to use pandoc in standalone mode, you’ll need to extract pandoc binary executable from the installer file – for some reasons, the standalone version is no longer available for download. The installer contains two binary files (pandoc.exe and pandoc-citeproc.exe), the html User’s Guide and the license files.

1. Dowload the pandoc msi installer (eg: pandoc-1.XX-windows.msi)
2. Unpack it (using 7-Zip) and extract and rename the pandocEXE file to pandoc.exe
3. Optionally (if you need to use CiteProc for working with citations and bibliography files) also extract pandoc_citeprocEXE and rename it to pandoc_citeproc.exe.

Make sure that pandoc.exe (and, eventually, pandoc_citeproc.exe) is reachable via %PATH%, or just put it in the same folder as the 2bbcode.lua script and the documents you want to convert (this is a good solution if you want to keep all your work within one folder).

Pandoc Supported Input Formats

As of pandoc v1.19, the supported input formats are:

• commonmark – CommonMark Markdown.
• docbook – DocBook.
• docx – Word docx.
• epub – EPUB.
• haddock – Haddock markup.
• html – HTML.
• json – JSON version of native AST.
• latex – LaTeX.
• markdown – pandoc’s extended Markdown.
• markdown_github – GitHub-Flavored Markdown.
• markdown_mmd – MultiMarkdown.
• markdown_phpextra – PHP Markdown Extra.
• markdown_strict – original unextended Markdown.
• mediawiki – MediaWiki markup.
• native – native Haskell.
• odt – ODT (Open Document Format for Office Applications).
• opml – OPML (Outline Processor Markup Language).
• org – Emacs Org mode.
• rst – reStructuredText.
• t2t – txt2tags.
• textile – (subsets of) Textile.
• twiki – TWiki markup.

You can view a list of all input formats supported in pandoc by typing:

pandoc --list-input-formats

2bbcode's Issues

On linux, the script does not work as documented on the readme

doing :

./2bbcode -f org < ../orgModeFile.org

returns nothing, doing:

./2bbcode org < ../orgModeFile.org

(removing the "-f")

works as expected (this is pretty obvious if you read the script, it just passes the first argument to the -f flag of pandoc) ,

I think modifying the script to:

exec pandoc -t "$me"/bbcode.lua "$@"

will work better (basically passing all the parameters to pandoc).

Can you please show me how to save output file to another location?

Hey I am trying to use your software and it works out of the box, I wonder if you could help me with this little issue though.
I am very new to this and scripting in general, so please bear with me if I seem slow.

.\2bbcode.bat example.md
The above works fine and prints out a bbcode file in the same directory as the 2bbcode.bat file. I am trying to get the output file saved to another directory, I have tried
.\2bbcode.bat .\example.md -o .\test\test.bbcode
It just saves it to the same location as the 2bbcode.bat file.

Can you please show me how to save it to another location? Am on windows. Thank you.

integrate upstream?

it would be a easier if this would be upstream, it can save having an extra executable on my system, That's a little less clutter (which makes searching files a little easier) and one less piece of software that needs to be manually updated.

It could also lead to a few more eyes on the code, meaning maybe more better feedback and more improvement's to the code.