Hi Ian,
= Definition =
I agree that the word 'stanza' is somewhat of an uncommon term in the realm of
computing, however there is precedent in the domain of XML [1]. The usage in
that spec admittedly implies a sense of plurality and yet an XML element could
of course span multiple lines but actually represent an empty value:
<message>
<message/>
According to wiktionary and Websters [2], stanza can also mean a division or
simply a poetic unit without prescribing a minimum length (as the OED does). I
suspect (?) Scott might have been thinking along those lines when he adopted the
term.
= Multi-line singular stanzas in Upstart =
Note that even those singular Upstart stanzas such as 'author' and 'console' can
span multiple lines using the usual back-slashing technique if so required:
console \
\
\
log
author \
\
"james"
That facility again lends weight to the use of the term for any type of Upstart
stanza; each stanza is a logical unit the encapsulates certain meta-data or
requirements for the job environment.
= Occurrences of the term in the code =
Interestingly, aside from the man pages, there are only 2 occurrences of the
word stanza in the code that users will ever see:
1) init --help|grep -iB1 stanza (reformatted below)
--default-console=VALUE default value for console stanza
Clearly, this would be trivial to change if required.
2) The error "Unknown stanza" resulting from failing to parse an invalid job
configuration file. This error comes not from Upstart but from the dependent
libnih which actually performs the safe parsing of all the Upstart job
configuration files.
I'm not convinced we should change libnih. In fact, it is Scott we'd really need
to convince since the stanza code in libnih has been around since ~2007 fwics.
= Proposed Plan =
In summary, would you be happy if we defined 'stanza' more clearly in the manual
pages, making reference to terms such as 'command' and 'keyword' and giving
examples of single-line and multi-line stanzas so there is no misunderstanding
as to what is meant by the term?
Kind regards,
James.
[1] - http://xmpp.org/rfcs/rfc3920.html#stanzas
[2] - http://en.wiktionary.org/wiki/stanza
--
James Hunt
____________________________________
#upstart on freenode
http://upstart.ubuntu.com/cookbook
https://lists.ubuntu.com/mailman/listinfo/upstart-devel
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
