Steno is an HTML5 webapp used by Openbylaws.org.za to capture by-laws and process them into XML for use on the website.
Anyone can use the app running at steno.openbylaws.org.za.
How to use Steno
- Get a PDF or other version of the by-law to parse
- Visit steno.openbylaws.org.za
- Enter the full title of the by-law and the region it applies to
- Choose a short name. This will be used in filenames and should be all lowercase and not have any spaces.
- Enter the gazette the by-law was published in, its number and date.
- Choose the title format the by-law uses
Looks good, next step
- Enter the plain-text of the by-law into the text box.
- Steno will show you an errors it finds while trying to parse the text.
- Use the HTML preview on the right to check that the by-law parsed sanely. Look for issues such as broken lists, missed headings and unnecessary newlines.
- Make corrections to the plain-text and click
Parse textuntil you're happy
Looks good, next stepto view the XML.
- Edit the XML as necessary and click
Previewuntil you're happy.
Looks good, next stepto go to the final step.
Save to Githubto save the file to Github and send a pull request.
Saving to Github
You need to authorise Steno as a Github application. It will prompt you to do this when you first try to save to Github.
Steno will create a fork of the za-by-laws repository if you don't already have on. It will then save the new file to a new branch based on the short name of the by-law and submit a pull request.
You can safely go back, edit the document or XML, and click
Save to Github again.
How Steno works
Steno's goal is to lower the bar for taking by-laws in plain-text (generally cut-and-pasted from a PDF) and transform them into Akoma Ntoso XML for use on the openbylaws.org.za website.
Steno has a grammar which does its best to make sense of a plain text version of the by-law. It finds structure such as lists, nested lists, sections, parts and chapters.
Developing and contributing
To run tests, use either
to run the specs once off, or use
to run them continuously.
We welcome pull requests!
Steno is a Sinatra ruby app. To install and run it locally,
- clone the git repo
Steno runs on heroku:
git remote add heroku firstname.lastname@example.org:steno-openbylaws.git