Resource bbcoder - BBCode Generation Tool [0.2.0]

[Lyro]

bbcoder is a command-line application which simplifies the writing of complex BBCode posts. When a post reaches a certain size and complexity, I find it can become difficult to find your place in your code to make a simple change, a problem that is compounded when you wish to make the same change in multiple areas.

Enter bbcoder. Instead of writing BBCode, you write in a simple, custom XML-based markup language I have created called BBXML. If you've ever written some HTML, it should look very familiar. BBXML offers the following features over BBCode:

• Classes: you can assign a class to any BBCode which has an option (e.g.
  [DIV=]
  ). A class is mostly intended for CSS properties in combination with
  [DIV]
  , but it could be used for any type of option content. You start by defining a class somewhere in your project, giving it a name and a value; you can then re-use that class's value for any tag, avoiding the need to copy-paste CSS properties constantly.
• Templates: if a class isn't enough, you can use a template. This is a more powerful tool as it lets you define a BBXML template, with optional parameters, then insert that template in your post. A simple example is a status box for your character: you would define the formatting once, and then for every subsequent post you just have to include the status box template, filling it in with the character's mood, location, etc.
• Project structure: BBXML can be split over multiple files that are then combined to create a single BBCode post. This allows you to define commonly-used code in one file and create one file for each new post you make.
• Insensitive to whitespace or newlines: being able to make a new paragraph just by pressing Enter is convenient when writing standard RP posts, but for formatting-heavy posts it can be a nightmare. BBXML requires that line breaks be explicitly specified with the
  <br />
  tag.
• XML-based syntax: one indirect advantage of using BBXML is that it will look very familiar to most editors. This means you can get all the advantages of traditional code editors, such as syntax coloration, auto-completion, etc.
• Browser extension: you don't have to install bbcoder if you want to try it out. Check out the Chrome and Firefox browser extensions, which add a BBXML editor to RpNation.

The new workflow when using bbcoder is to create your project, build one of its targets (i.e. a specific post), and copy the resulting BBCode to your post. This may be improved somewhat in later releases.

C

Usage

Quick Start

1. Download bbcoder for your system
2. Extract the archive contents somewhere on your computer
3. Run bbcoder
   • Windows: just double-click on the
     bbcoder.exe
     file
   • macOS: make a note of the location where you extracted bbcoder, open Terminal, type
     cd /the/path/to/your/bbcoder/folder
     (replacing it with the actual path to the contents of the archive), then type
     ./bbcoder
   • Other operating systems: you'll have to compile the program from source for your system.
4. You should now have a file in the
   targets/
   folder called
   sample-post.txt
   . Congratulations, you've just built your first BBXML target!

Installation

bbcoder consists of a single executable file, bundled with a starting project structure. To install it, just download the archive, extract it somewhere on your computer, and you're set up!

If you just wish to try out the functionality or don't need the full flexibility of a project, you can download and install the browser extensions instead.

Setting up your project

bbcoder works on BBXML projects - a set of files linked together through inclusions and a master project definition file. bbcoder is distributed with a skeleton project you can fill in as you go, consisting of the following files:

• project.xml
  : this file defines your project and lets bbcoder know where the other files are. It consists of the following sections:
  • : defines a set of paths to BBXML files located anywhere on your computer. Useful if you want to have a common folder located outside of your project directory, for example.
  • : defines the targets (i.e. posts) which bbcoder will build. Each target has a name and a source file: bbcoder reads the source file, then outputs the target BBCode in a file with the target's name. By default, all targets that are defined will be built, but you can set the
    default
    attribute to the target you want to build. In the sample project, it only defines one target called
    sample-post
    .
• src/sample.xml
  : a sample BBXML post file. When you run bbcoder, this will create a file called
  target/sample-post.txt
  .

Of course, this is just a very basic project. As an example, my personal project currently consists of about 20 post files, along with a few library files (i.e. files that are only included, not used to build posts), all organized within several folders.

Creating a new target

Say you want to create a new target: you'll need to create a new source file for it and a new target entry in

project.xml

. A source file consists of four key sections.

The

include

tags allow you to include other files in this project, which lets you re-use classes and templates defined in other files.

The

classes

section defines the classes you can use in your project. Each class is identified by a name and a value. The value can be arbitrary text, but this is usually CSS and functions somewhat like a CSS class.

The

templates

section contains template definitions. You can see these as more advanced classes, which you can use when you want to re-use a bunch of code. Templates can contain parameters, which take the form of

{your_parameter_name}

. These will be replaced by their new values when the templates are included. The inside of a template works just like the

body

section.

Finally, the

body

contains your actual post. Here, almost any tag you use will be interpreted as a BBCode tag (e.g.

<b></b>

is the same as

[b][/b]

). There are a few key differences however:

• Classes and options: every BBCode tag supports options using
  =
  can have a class (or classes) and an option specified. The
  class
  attribute can be used to specify a list of space-separated classes, while the
  option
  attribute indicates values specific to this tag. They can be used together, in which case the specific option will be appended to the end of the class's value. Example:
  <div class="class1 class2" option="background-color: yellow;">
• Including templates: you can include templates using the
  <include>
  tag, which indicates the name of the template to include. The body of the tag then contains a list of
  <p>
  tags indicating the values of the template's parameters. The value can be simple text or additional BBXML code.
• Line breaks: you have to explicitly require a line break using the special
  <br />
  tag.
• Lists: list elements must be surrounded by
  <li></li>
  tags instead of prefixed by
  [*]

Note: you can abbreviate a lot of these names:

• The
  class
  ,
  option
  and
  template
  attributes can be shortened to
  c
  ,
  o
  and
  t
  , respectively.
• The
  div
  ,
  include
  and
  param
  tags can be abbreviated to
  d
  ,
  in
  and
  p
  , respectively.

Building

You can then build your project simply by running bbcoder from the root of your project. The resultant BBCode will be in the

target/

subdirectory.

C

Downloads

The current version is 0.2.0. This is a stable release - it is mostly feature-complete, and while there might be a few bugs, they are likely to be very minor.

The recommended way of running bbcoder is from the command-line (on Windows this is the Command Prompt by default, and on macOS this is the Terminal).

As an example of a setup: I use IntelliJ IDEA (a free IDE) for editing BBXML projects. I have configured bbcoder as an External Tool and bound it to F10 - whenever I want to build the BBCode, I just hit F10 and copy the result.

Warning: your browser may inform you that the file is potentially dangerous because it is not frequently downloaded. This is normal. If you have any doubts as to its security, feel free to look at the source code and to compile it yourself.

Windows: bbcoder-win-0.2.0.zip

macOS: bbcoder-mac-0.2.0.zip (the macOS build might lag behind a few versions)

Google Chrome extension: https://chrome.google.com/webstore/detail/bbcoder-for-rpnation/ldbjelfkggmnndhpmnanakbgjfgmooho/

Firefox extension: https://addons.mozilla.org/en-GB/firefox/addon/bbcoder-for-rpnation/

Source Code: https://github.com/Lyrositor/bbcoder

C

Planned Features

I am planning on working on the following features for upcoming releases; this is not a promise that they will be released, just an indication of what I'd like to see implemented:

• Aliasing: BBXML can be very verbose (as is XML), and I would like to provide a way to alias certain frequently-repeated parts.
• Live preview: I have an idea of how this could be implemented. Essentially, it would watch your project, and whenever a file is updated, it re-compiles the BBCode and displays a preview of the result in your browser.
• Better error messages: it's not always clear where an error in your project comes from currently; I hope to improve this.
• Ease of use: various quality of life improvements to make installing and using bbcoder simpler

Known bugs

• Circular includes aren't currently detected

C

License

bbcoder is licensed under the CC0 1.0 Universal license. Essentially, it has been released into the public domain, and you are free to use, modify or distribute its code without providing attribution (though it would be appreciated).

C

Source

The BBXML source code for the original version of this post has been provided as an example:

• project.xml
  : https://gist.github.com/Lyrositor/a8d0b9f1609c78d7cec2b402980f9103
• src/lib/common.xml
  : https://gist.github.com/Lyrositor/0e214d0039cb5204bcc2475281d88a14
• src/bbcoder-post.xml
  : https://gist.github.com/Lyrositor/c0cf4577e955ceca4cc4ac2362767b0a
• BBCode: https://gist.githubusercontent.com/Lyrositor/391f4d60b3a6a60eac17204c4da6dcaf/raw/bbcode.txt

 

[Lyro]

A macOS version has been made available in the original post (thank you C.DEX !). Just like for Windows, it's a command-line application. And just like Windows, it comes with a script you can run which should make running it a bit simpler.

I currently do not have any plans to make a graphical user interface for bbcoder, but if there is demand for one I can try to provide a simple one (unfortunately there is currently a lack of good GUI libraries in Rust).

 

[Lyro]

Version 0.1.1

Changelog:

• [FEATURE] New attribute on elements: add
  plain="true"
  to prevent bbcoder from removing whitespace and newlines; useful if you want to show some BBCode or HTML as you wrote it
• [CHANGE] Don't replace parameter tags (e.g.
  {param}
  ) if the parameter wasn't provided
• [BUG] Text was being unintentionally duplicated after use of
  <br />

 

[Lyro]

Version 0.1.2

Changelog:

• [FEATURE] Common tags and attributes in body can now be abbreviated:
  • div
    tag:
    d
  • include
    tag:
    in
  • param
    tag (in an include):
    p
  • class
    attribute:
    c
  • option
    attribute:
    o
• [FEATURE] Default target is now
  _all
  , a special target which builds all user-defined targets

I would like to take advantage of this release to highlight some of BBXML's advantages over BBCode. To be clear, everything that can be done in BBXML can be done in BBCode; bbcoder simply converts the BBXML to BBCode. However:

• For large projects, BBXML can require significantly less code than BBCode. As an example, the first post in this thread requires (when minimized) 13 559 characters in BBXML versus 19 966 in BBCode - a 32% decrease in character count. This is thanks to its class and template system, which lets you re-use the same CSS properties and bits of code without having to copy-paste it each time.
• BBXML lets you air out your code. No longer do you have to hunt down for that one tag you're looking for - you can see the entire structure of your post at a glance.
• BBXML can be used in most text editors, which provide syntax-highlighting and auto-completion. I cannot stress how much this can increase productivity. I personally like to use Notepad++ and IntelliJ (a Java IDE which can also handle XML).

If anyone would like to give bbcoder a try, please let me know what you think of it; I can help you set it up if you are having difficulties. I'm still working on adding new features.

Here are some examples of recent projects I have done using BBCoder:

• An accordion converted to look like a folder that slides open, revealing a character sheet
• A set of computer terminals serving as a character sheet`
• A horizontal accordion

Finally, here's the source code of another smaller commission that highlights the advantage of classes (note that this was released before this update; it could now be shortened further):

<bbxml>
    <classes>
        <class name="container">
            background-color: #e2ead0;
            border: solid 1px #E0E0E0;
            border-radius: 20px;
            margin: 0 auto;
            overflow: hidden;
            position: relative;
            width: 500px;
            z-index: 1;
        </class>

        <class name="globe">
            background-image: url(https://upload.wikimedia.org/wikipedia/commons/thumb/0/0e/Globe_centered_in_the_Atlantic_Ocean_%28green_and_grey_globe_scheme%29.svg/500px-Globe_centered_in_the_Atlantic_Ocean_%28green_and_grey_globe_scheme%29.svg.png);
            bottom: -50%;
            color: transparent;
            height: 500px;
            opacity: 0.2;
            position: absolute;
            right: -50%;
            transform: rotate(-20deg);
            width: 500px;
            z-index: -1;
        </class>

        <class name="header">
            background-color: #d0d8be;
            border-bottom: solid 3px #4b5435;
            color: #4b5435;
            font-size: 28px;
            font-weight: bold;
            height: 38px;
            padding: 5px 30px;
        </class>

        <class name="state">
            font-family: Lobster Two;
            font-size: 48px;
            font-style: italic;
            left: 20px;
            margin-right: 20px;
            position: absolute;
            top: -7px;
        </class>

        <class name="title">
            font-family: Source Sans Pro;
            font-size: 34px;
            position: absolute;
            right: 100px;
            text-align: center;
            text-transform: uppercase;
            top: 2px;
        </class>

        <class name="id">
            color: rgba(255, 255, 255, 0.79);
            font-family: Source Code Pro;
            font-size: 22px;
            left: 10px;
            position: absolute;
            text-shadow: 0px -2px black;
            top: 60px;
            transform: rotate(180deg);
            writing-mode: vertical-rl;
        </class>

        <class name="portrait">
            float: left;
            margin: 20px 10px;
            width: 175px;
        </class>

        <class name="content">
            margin: 10px 10px 10px 200px;
        </class>

        <class name="info">
            display: inline-block;
            margin-bottom: 5px;
            margin-right: 5px;
        </class>

        <class name="label">
            font-family: Bitter;
            font-size: 11px;
            font-style: italic;
        </class>

        <class name="field">
            font-family: Source Sans Pro;
            font-size: 14px;
            font-weight: bold;
            text-shadow: 0px 0px 0px black;
        </class>
    </classes>

    <templates>
        <template name="id-card">
            <div class="container">
                <div option="display: none;"><font option="Bitter">FONT</font><font option="Source Sans Pro">FONT</font><font option="Source Code Pro">FONT</font><font option="Lobster Two">FONT</font></div>
                <div class="globe">GLOBE</div>
                <div class="id">{id}</div>
                <div class="header"><div class="state">{state}</div><div class="title">ID Card</div></div>
                <div class="portrait"><img>https://s3.amazonaws.com/cdn.roosterteeth.com/uploads/images/e8606981-1731-44d5-9909-974c266f322f/md/2028444-1441426352670-Zero_Punctuation.jpg</img></div>
                <div class="content">
                    <div class="info" option="display: block;"><div class="label">Customer #</div><div class="field">{customer}</div></div>
                    <div class="info" option="display: block;"><div class="label">Name</div><div class="field">{name}</div></div>
                    <div class="info" option="display: block;"><div class="label">Address</div><div class="field">{address}</div></div>
                    <br />
                    <div class="info" option="width: 90px;"><div class="label">Sex</div><div class="field">{sex}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Class</div><div class="field">{class}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Date of Birth</div><div class="field">{dob}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Eyes</div><div class="field">{eyes}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Endorsements</div><div class="field">{endorsements}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">ISS ORI</div><div class="field">{ori}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Height</div><div class="field">{height}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Restrictions</div><div class="field">{restrictions}</div></div>
                    <div class="info" option="width: 90px;"><div class="label">Exp</div><div class="field">{exp}</div></div>
                </div>
            </div>
        </template>
    </templates>
    <body>
        <include template="id-card">
            <param name="id">T10000001 01 01 1970</param>
            <param name="state">Virginia</param>
            <param name="customer">T10000001</param>
            <param name="name">John Smith</param>
            <param name="address">123 Fake Street<br />Falseton, VA 10000</param>
            <param name="sex">M</param>
            <param name="class">NONE</param>
            <param name="dob">01/01/1970</param>
            <param name="eyes">BRO</param>
            <param name="endorsements">NONE</param>
            <param name="ori">01/01/2001</param>
            <param name="height">6FT 1IN</param>
            <param name="restrictions">NONE</param>
            <param name="exp">01/01/2030</param>
        </include>
    </body>
</bbxml>

 

[Lyro]

Version 0.2.0

Changelog:

• [FEATURE] Added a browser extension for Google Chrome which embeds a BBXML editor into RPNation
• [BUG] Some template parameters weren't getting replaced correctly

The big addition here is a Google Chrome extension which adds a BBXML editor directly to RPNation, so that you don't have to install bbcoder on your computer to use it! It was made pretty quickly so it's not very pretty or full-featured, but it should get the job done.

Download: bbcoder for RPNation

A note on privacy: this extension sends the BBXML data to my personal server for it to be converted using bbcoder. I don't keep the data after processing it, but if you are afraid I might spy on you, I understand if you don't want to install this extension, since you only have my word for it.

Here's a screenshot of what it looks like:

 

[The Dark Wizard]

This is intense and only just realized.

 

[ewolf20]

Version 0.2.0

Changelog:

• [FEATURE] Added a browser extension for Google Chrome which embeds a BBXML editor into RPNation
• [BUG] Some template parameters weren't getting replaced correctly

The big addition here is a Google Chrome extension which adds a BBXML editor directly to RPNation, so that you don't have to install bbcoder on your computer to use it! It was made pretty quickly so it's not very pretty or full-featured, but it should get the job done.

Download: bbcoder for RPNation

A note on privacy: this extension sends the BBXML data to my personal server for it to be converted using bbcoder. I don't keep the data after processing it, but if you are afraid I might spy on you, I understand if you don't want to install this extension, since you only have my word for it.

Here's a screenshot of what it looks like:

hi, hoow can you run it. noob question i know.

 

[Lyro]

hi, hoow can you run it. noob question i know.

You'll need to use the Chrome web browser, then click on the download link to the extension I provided and click the "Add to Chrome" button. This will add an editor box below the standard editing boxes - click the "Convert to BBCode" button to perform the conversion from BBXML to BBCode.

 

[ewolf20]

You'll need to use the Chrome web browser, then click on the download link to the extension I provided and click the "Add to Chrome" button. This will add an editor box below the standard editing boxes - click the "Convert to BBCode" button to perform the conversion from BBXML to BBCode.

Is bbxml like html and dad code?

 

[Lyro]

Is bbxml like html and dad code?

I don't know what "dad code" is, but yes, it is similar; here's an example.

 

[The Dark Wizard]

You'll need to use the Chrome web browser

Any chance for a firefox extension ?

 

[Lyro]

Any chance for a firefox extension ?

Sure - I need to polish the extension anyway, it's kind of a rough first draft at the moment, so the next version should be available for Firefox too.

 

[The Dark Wizard]

Sure - I need to polish the extension anyway, it's kind of a rough first draft at the moment, so the next version should be available for Firefox too.

Woot.

Firefox has been stepping up their game and I'm super stoked for their new web engine. I want to see if we can collaborate later and create an RpN Suite for Chrome/FF. Been working on browser themes for both !

 

[ewolf20]

I don't know what "dad code" is, but yes, it is similar; here's an example.

Css. Not dad code.

 

[Lyro]

Version 0.2 (Browser Extension)
The browser extension has been updated and significantly overhauled (no changes to the main bbcoder program)!

Changelog:

• Firefox support has been added, in addition to Chrome
• Now lets you switch between BBXML mode (which works just like before), BBCode mode (BBCode with syntax highlighting and non-matching tags warnings) and the normal editor box
• BBXML is automatically generated when either the Create/Reply button is pressed or the post is previewed

Notes:

• Quoting/Replying currently only works in "normal" mode - this may change in the future
• While I have tested as much as I can on my system to ensure everything works, there might still be issues. If you find you're writing a long and complex post, you might want to copy-paste your code before posting, to avoid losing any data.

Known Bugs:

• List items ([*]) mess up the syntax highlighting because it doesn't have a matching closing tag. I hope to have a fix out soon, it shouldn't be too complicated.

Download (Chrome): v0.2.0 (Chrome)

Download (Firefox): v0.2.0 (Firefox) (as of this writing, the add-on is undergoing its first review by Mozilla, but it can still be downloaded)

 

[Lyro]

I have updated the original post to include a quick start guide and the latest version (0.2.0) for macOS. The download files have also been updated to include a sample project to let you get started immediately. On Windows, this is a one-click affair!

Considering the Chrome and Firefox browser extensions that are now available, this means that is has never been easier to try bbcoder - whether as a stand-alone tool or as a part of your browser. If you give it a go, please let me know what you think. Comments and feedback really motivate me to keep working on this.

 

[ewolf20]

hi Lyro , if you're there, i still can't seem to get it to work. i don't see the button and the .exe doesn't load up.

 

[ewolf20]

i don't know what i'm doing wrong. it won't turn on or something.

 

[Lyro]

i don't know what i'm doing wrong. it won't turn on or something.

What is your browser? Are you sure you downloaded the extension from the appropriate browser app store?

 

[ewolf20]

What is your browser? Are you sure you downloaded the extension from the appropriate browser app store?

google chrome

 

[Lyro]

google chrome

I don't have enough information about your problem to say what's wrong. Could you screenshot your Extensions page (go to chrome://extensions/ ), as well as your reply box?

Have you also made sure to disable the rich text editor too in your preferences? If it is enabled, my extension will not work.

 

[ewolf20]

I don't have enough information about your problem to say what's wrong. Could you screenshot your Extensions page (go to chrome://extensions/ ), as well as your reply box?

Have you also made sure to disable the rich text editor too in your preferences? If it is enabled, my extension will not work.

i did that. still doesn't see, to work.

 

[Lyro]

The EXE shouldn't display anything, it's a command-line program. You just click on it and it runs silently, maybe opening up a console window briefly.

The extension will only work if the RTE is disabled.

 

[k a l l i s t o]

Hello, I have a question(s) about your extension: Is there any possible way for me to view both BBCode or BBXML without one or the other being removed as I transition between tabs? Is there a potential 'save' option being added in future, perhaps?

 

[Lyro]

Hello, I have a question(s) about your extension: Is there any possible way for me to view both BBCode or BBXML without one or the other being removed as I transition between tabs? Is there a potential 'save' option being added in future, perhaps?

Currently, there are no such options planned. Is there a particular reason why you'd want to do this?