[r-t] Leary's 23-spliced

[Don Morrison]

On Tue, Aug 19, 2008 at 4:21 PM, List01 <list01 at shropshirelad.idps.co.uk> wrote:
> Can you give details of the XML format so that people can submit things to
> you in a format that you can quickly upload?

For things being newly submitted the format is not the major stumbling
block. Computer proof, and in a form that emits the form that will be
uploaded, is the major stumbling block there. It's startling the
number of things folks submit that have errors of one sort or another.

It's been several years since I've been directly involved in dealing
with such submissions myself, but when I last was nearly 30% of what
we received in one year had some sort of error in it. The most common
was one or more incorrect course heads, but some were false, some too
short, and some didn't come round as submitted. In most cases it was
not that folks hadn't computer proved their compositions, rather it
was that what they submitted differed from what they had proved.

Most of what goes on the site has had its printed representation
generated directly from the proving software. In some cases there
needs to be subsequent hand-tweaking, which is unfortunate because in
those rare cases where there are errors introduced, that is almost
always the source.

Given this high error rate in submissions, most things submitted need
to be proved, and the output of the proving software used, which would
obviate any benefit to submitting them in the XML format.

The long term solution to this is to make proving software available
that generates things in the right format. Then folks could submit
their compositions in the input format for this software, and
everything could be automated below that. The software I use myself is
part way towards this, but is in a form that only its author could
love. I am partway into rewriting it, with an intention of making it
friendlier to use, able to emit things in a format that can be
automatically uploaded, documenting it, and making it available to
anyone interested. How long until this sees fruition, though, I'd not
be willing to guess. It rises to the top of my pile for a few weeks at
a time, but then sinks back down again when something else more
important comes along.

The reason this is not a problem when formatting collections for
pouring in is that they've already been through a fairly stringent
review process and most errors have been squeezed out by repeated
proof reading and so on. And most recent collections have had their
printed representations directly created by the proving software, in
some cases in software designed specifically for the collection in
question.

All that said, though, if anyone is interested in the XML format you
can learn a bit about it by casting your eye over the following, which
I've cribbed from a message to someone else a while ago. Be sure to
note the bit at the end which shows how to dump the XML for any
composition you might want to use as an example.

---------------------------------------------------------------

No schema, but there's a DTD at

 http://ringing.org/compositions.dtd

I've also put a few examples at

 http://ringing.org/examples.zip

I zipped the file as a web browser might otherwise try to interpret the xml
instead of displaying it as text, or downloading it!

Of course, the DTD is only a fraction of the story. Here's some other
stuff you'll need to know:

- Note that the stage names and method classes are case sensitive, and
must be all lower case. Stuff will be in proper title case, and without
hyphens, when actually presented on the web page

- the method names should be title case; for spliced the method name
should be "Spliced"

- for entering new compositions (as opposed to modifying ones already
in the database) don't supply an id attribute or a date-entered
attribute -- the software will do that

- for things entered by the committee the submitter should always
be "1"

- series and alternate-sort you probably don't need to supply; if we
run into a case where such a thing becomes important we can discuss
it when needed

- opus is printed in parens right after the composer(s); it's typically
something like "no. 3"

- if there are multiple lengths possible each should have its own
<length length="NNNN"/> -- the first is the one presented normally, and
the rest show up after it in parens

- the number in the length="NNNN"/> should be an integer formatted
without commas -- the commas are added when the web page is displayed

- The <method.../> that come right after the opening of
a <composition> need only be used for spliced, or where the attributions
in the <composition....> don't completely define the method.

- in <method.../> you probably just need to supply the name, class and stage,
and not worry about the other stuff

- the contents of <calling>...</calling> will be displayed in a fixed
width font, with line breaks preserved, and should be arranged to so line up

- where you want rules to appear, use lines with just sequences of
underscores and spaces; they'll get converted to HTML <u>...</u>s as
appropriate when displayed

- any occurrences of % will get turned into a single character 1/2

- don't use any fancy characters there; just 7 bit ASCII

- be careful to format only with spaces, no tabs!

- the <calling>...</calling> should include any rubrics like "Repeat twice."
or "Call s for - halfway and end", as well as descriptions of funny calls
such as "s = 1256." or blocks of calls such as "3* = s - s.".

- further descriptive matter such as music counts, other methods the
composition is true to, or alternative callings should go into the
<notes>...</notes>.

- I generally find using a CDATA section for <notes> handy, as it can
contain further markup sometimes

- the contents of <notes>....</notes> is presented in a variable width
font, and is word wrapped as necessary. Generally things should be in there
without any line breaks, except where you want to explicitly force one.

- any occurrences of underscores in <notes>...</notes> are turned into
non-breaking spaces; % are again turned into 1/2 characters

- for spliced, and the methods enumerated in <notes> should have, at least
once per occurance, a form with their name surrounded by
<method...>...</method>. See the example to make this clear. This allows
a hyperlink to show up at display time, that, if clicked on will show the
method

- the <notes> need to include descriptions of universal truth and other
methods true to -- the <true-to> elememnt described below doesn't actually
generate any text, it just adds cross reference type info to the database

- <true-to> is used two different ways; either may exist without the
other, or both may appear if appropriate: the first is as a decription
of things universally true to -- the attributes are used to specify the
apprpriate lead head groups, and the FCH groups

- other other use is with <method>s in the body of the <true-to> which
enumerate other methods this composition is true to

- when using <true-to> don't forget to put appropriate text into the
<notes>, too

- unlike <true-to>, the <rung-at> element *does* produce text

- in <rung-at> the county attribute is only supplied if the town name is
otherwise ambiguous; similarly the dedication is only supplied if the town
(possibly the town in that county) has multiple towers

- the modifier is rarely used; it's replaces the word "Rung" at the
beginning of the generated text. The most common uses are things like
"Rung to Blitheringstrange Surprise", or "Rung on handbells"

- for things published in the RW the collection is "The Ringing World" and
a year and page should be supplied. For other collections, speak with me
for details so collections are named consistently.

I'm sure I've skipped over things that are now obvious to me in hindsight,
but will cause confusion to folks using this stuff for the first time. Please
don't hesitate to ask! With luck the examples will help a lot.

You can generate further examples yourself easily from things in the
database by using the following URL

 http://ringing.org/main/pages/dump?id=NN

where NN is replaced by a composition's id number. This number can be
easily discovered by clicking the "printable" link for any composition.
Note that many web browsers will try to interpret the XML returned, so
you'll probably have to save the file to see it properly. Or use something
like wget or curl to download it directly (that's essentially what I did
to produce the file of examples cited above).





-- 
Don Morrison <dfm at ringing.org>
"Education is the reason why we behave like human beings. We are
hardly born human; we are born ridiculous and malodorous animals;
we become human, we have humanity thrust upon us."
                 -- Will Durant, "The Ten Peaks of Human Progress"