Updating the abc standard
The abc standard is open to new proposals from anyone, although proposals require support from the abc user community before being incorporated.
The aim of the following process is to provide an inclusive, transparent and considered method for updates to progress (and a procedure which doesn't have the bottleneck of requiring my input at every stage).
Guidelines for new syntax
In order of importance, the aims for any new syntax are that it should result in abc code which is clear, suggestive and compact; furthermore, the syntax should be unique, if possible, and its description in the standard should be concise and straightforward.
the resulting abc code should be as clear as possible to humans, preferably without requiring the reader to look up the usage in the standard
the resulting abc code should be suggestive of standard staff notation, provided that this does not compromise (1)
the resulting abc code should be as compact as possible, provided that this does not compromise (1) and (2)
the syntax should, where possible, provide a unique method to achieve each effect, provided that this does not compromise (1), (2) and (3)
the description of the syntax should be concise, i.e. giving a lot of information clearly and in a few words, and straightforward, i.e. uncomplicated and easy to understand, provided that this does not compromise (1), (2), (3) and (4)
This means that, for example, minimising the size of the abc code is not the first priority if it reduces clarity and suggestiveness. It also means that it is acceptable to have two methods of achieving the same effect, particularly if it helps clarity. Finally, although it is important that the standard document does not become bloated and overcomplicated, ultimately it is the clarity, suggestiveness and compactness of the resulting abc code which has a higher priority.
Submitting a proposal
The process for submitting a proposal is as follows:
- before doing anything else, make sure that there is some interest from the abc user community in supporting the proposal. Currently the best way to do this is by discussing it on the abcusers mailing list
. You should also familiarise yourself with the abc standard route-map
to make sure your proposal fits in with the general principles and direction of the standard.
for an account on the abcnotation wiki. Your password will be sent from cwalshaw [at] jdz3 [dot] dailyrazor [dot] com so if you don't get an email shortly, check your spam folder.
with the following information (I will then create a section of the wiki site and give you write access):
your account username;
the subject of your proposal;
optionally, if you want to collaborate on a proposal, the usernames of any other users who you would like to have write access to the proposal (write access can also be granted later on).
Once your proposal is finished, email me
and I will set up a poll. The proposal will be locked so that it cannot be modified during the voting.
If your proposal is supported, it will be edited (by me) and incorporated into the standard; if not, go back to step 4. There is no precise number of votes you need for a proposal to be supported, but typically you are looking for 20-30 votes with most in favour; votes by developers of abc software have more weight than those by users.
It is quite possible that a proposal will go through several rounds of voting before being adopted - do not be discouraged, the aim is to make the standard as clear and robust as possible.
Recommendations for writing proposals
As far as possible you should write your proposal in the same format and style as the current abc standard. If you need help, please ask me
, although if I am busy (quite likely) I may require your proposal to go through at least one round of voting, to see what level of support exists, before helping with drafting.
It is strongly recommended that you keep the abc user community updated with changes and take on-board any comments and suggestions.
It is also recommended that you provide a series of draft documents rather than one continuously changing document, so that email discussions are always referring to a fixed version of the draft rather than something which has changed since the email was sent.
Instructions for using DockuWiki
The standard is formatted using DocuWiki
, a text-based collaborative documentation system that uses "a simple but powerful syntax which makes sure the datafiles remain readable outside the Wiki and eases the creation of structured texts". You should also, therefore, use the docuwiki syntax for formatting your proposal. There is a short guide to syntax on the DocuWiki site
and you can also look at the source text for any abcnotation wiki page by clicking on the "Show pagesource" button at the top and bottom of each page (note that if you are logged in, the "Show pagesource" button is replaced by an "Edit this page" button for any page which you have permission to modify).
To create a new page, just point your browser at the address of the page you require, e.g. http://abcnotation.com/wiki/abc:standard:v2.1:proposals:[your_proposal_name]:[your_user_name]:v2, and (if I've got the permissions right) there should be a "Create this page" button.
Chris Walshaw (Editor)