SignPuddle 3 Development Tools

These tools are required for SignPuddle 3 development. Shell scripts and python scripts automate the building of the client and server applications.




A general introduction to the foundational technologies of SignWriting is available in the Sutton SignWriting Project: online, download, and repo.

SignPuddle 3 is a two-part project: the client for the average user and the server for the developer and power user.

Automated scripts build both the client and the server of SignPuddle 3.

The ApiTxt Format is a custom text markup used to define a RESTful API.


SignPuddle 3 is currently in alpha release. It is under active development with rudimentary structures, basic outlines, and various functionality. Some of the details will change. This project is currently recommended for developers and power users.

The SignPuddle 3 Development Project is divided into five sections. The tools use the source to create the client and server. The system is required if the Apache web server isn’t available.

    | - Python scripts and shell scripts 
    | - ApiTxt Format
    | - HTML, CSS, and JavaScript
    | - PHP PHP Server or Apache
    | - Portable web server for Windows, Linux, and Mac 

The client is available for preview, with some structure to demo. The client includes developer documentation and basic tools for accessing the server API.

The server is available for use, with some functionality. Standard GET requests can be typed in any browser URL, such as The server can be accessed using JavaScript with the HTTP methods of GET, POST, PUT, and DELETE. Additionally, the client API pages provide total access and full details of live server requests.


SignPuddle 3 can be installed on a computer or USB drive. The source code is available using git.

cd Desktop  

# Either install in a new SignPuddle3 directory
git clone SignPuddle3

# Or install in current directory
git clone .

Software updates are also available through git.

cd SignPuddle3  
git pull

The server requires some configuration before it can be used.

cd SignPuddle3/server  

If an Apache web server is not available, you can start the system using the PHP builtin server. While the client code can function without a webserver, the server code requires a web server to function.

cd SignPuddle3/system  
# Windows  

# Mac or Linux  

Once started, SignPuddle 3 will be available on the same computer with two default URLs.

To access SignPuddle 3 on a different computer or device, use the computer’s individual IP Address available from the output of the start_system script.

        inet netmask 0xffffff00 broadcast
PHP 7.1.16 Development Server started at Wed Sep 19 11:15:04 2018
Listening on
Document root is /Users/slevinski/Desktop/SignPuddle3
Press Ctrl-C to quit.

In this example, SignPuddle 3 will be available with this URL.


Most users will access SignPuddle 3 with the client section: a combination of HTML, CSS, and JavaScript. The client section presents information graphically.

The client section can be used online or downloaded as part of the ApiTxt project. The client section can be opened using the file system and any standard browser.




The server section is a functional RESTful API written in PHP using the Slim Framework v2.

The server section requires an Apache webserver that can use rewrite rules. The rules are written in the server/.htaccess file.

Alternatively, the server section can use the built-in PHP webserver. See the system directory for more information.



Document segments are written in the source directory using ApiTxt Format: a highly structured plain text markup that fully defines a RESTful API. Each line in an ApiTxt document is a self-contained element which starts with a name and is followed by <TAB> separated fields.

ApiTxt Format uses eleven types of element to define an RESTful API: root, group, route, parameter, method, request, response, header, line, code, and body.


Python programs and shell scripts are used to read and write a variety of data formats including ApiTxt Format, JSON data, API Blueprint, HTML, JavaScript, and PHP scripts.

  • - From ApiTxt Format to an array of JSON objects.

  • - From an array of JSON objects back to ApiTxt Format.

  • - From an array of JSON objects to API Blueprint written in markdown.

  • - From an array of JSON objects to a functional PHP server using the Slim Framework v2.

  • - From an array of JSON objects to API Interface.

  • - From an array of JSON objects to JavaScript.

All of the tools use command line arguments. Use -h for help.

python -h
usage: [-h] [-i INPUT] [-o OUTPUT] [-e]

Conversion of plain text lines to an array of JSON objects

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        name of input file
  -o OUTPUT, --output OUTPUT
                        write to output file
  -e, --errors          check for errors and report

Make and Build

The tools/ file is used to create the build script.

The tools/ file is used to create the client and server sections.

cd SignPuddle3/tools

Snowboard (bukalapak/snowboard)

Used in the build script, snowboard can parse API Blueprint documents. Snowboard offers three different transformations: lint, html, and mock. Snowboard lint will check the structure of the markdown text and report errors. Snowboard html will create a stand-alone html document using a template. Snowboard mock will analyze the responses of the markdown document and serve static responses over HTTP.


The system directory contains a portable web server for Windows, Linux, and Mac. The system directory is useful for individual computers or private networks.

For public servers, do not use the system directory, instead use the Apache web server with rewrite rules.