README.md - Markdown version
index.html - HTML version
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.
The client is available for preview, with some structure to demo. The client includes developer documentation and basic tools for accessing the server API.
SignPuddle 3 can be installed on a computer or USB drive. The source code is available using git.
# INSTALL cd Desktop # Either install in a new SignPuddle3 directory git clone https://github.com/slevinski/apitxt SignPuddle3 # Or install in current directory git clone https://github.com/slevinski/apitxt .
Software updates are also available through git.
# UPDATE cd SignPuddle3 git pull
The server requires some configuration before it can be used.
# CONFIGURE cd SignPuddle3/server unzip Slim.zip
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.
# START cd SignPuddle3/system # Windows start_system.bat # Mac or Linux ./start_system.sh
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.
./start_system.sh inet 192.168.254.6 netmask 0xffffff00 broadcast 192.168.254.255 PHP 7.1.16 Development Server started at Wed Sep 19 11:15:04 2018 Listening on http://0.0.0.0:8888 Document root is /Users/slevinski/Desktop/SignPuddle3 Press Ctrl-C to quit.
In this example, SignPuddle 3 will be available with this URL.
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.
Source: ApiTxt format and JSON objects
Documents: API Blueprint and Stand Alone HTML
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.
txt2json.py - From ApiTxt Format to an array of JSON objects.
json2txt.py - From an array of JSON objects back to ApiTxt Format.
json2md.py - From an array of JSON objects to API Blueprint written in markdown.
json2php.py - From an array of JSON objects to a functional PHP server using the Slim Framework v2.
json2html.py - From an array of JSON objects to API Interface.
All of the tools use command line arguments. Use -h for help.
python txt2json.py -h usage: txt2json.py [-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
The tools/make.sh file is used to create the build script.
The tools/build.sh file is used to create the client and server sections.
cd SignPuddle3/tools ./make.sh ./build.sh
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.