[Tcs-lc] Human Readable - the thread formally known as 'Name of NomenCode'

Sally Hinchcliffe S.Hinchcliffe at rbgkew.org.uk
Tue Mar 29 02:06:08 PST 2005


Roger wrote:
> I am all for readability and it is something I am just sitting down 
to 
> look at in the TCS today. This is partially inspired by trying to 
put 
> together some instance documents over the weekend. This matter does 
not 
> only include field names but also general structure.
> 
> How important do people consider it is to be able to read/hand 
craft TCS 
> instances - at least simple one?


I vote for readable, but not necessarily hand-writable. Another thing 
to look out for is making sure it's easy for programs to generate the 
stuff

readability enhances acceptance - if the instance documents look 
readable then people are more likely to use them, and they will feel 
confident that they will be able to troubleshoot any problems.

For writability, the main impact is on the wrappers producing the 
XML. When we did this in IPNI, producing the data via templates, the 
problem was keeping track of references within the document - for 
instance references to publications. The way a website like IPNI 
serves data up is as a stream of names with a header at the top and a 
footer at the bottom. It's easiest if each name and its associated 
data can be totally self contained with no need to keep track of a 
second set of data that's being referred to internally within the 
document. It's not impossible (we did handle references to 
publications in the TCS data we served) but the more internal 
references there are to keep track of the harder it is. Unfortunately 
recent discussion seems to be sending us down the internal reference 
root more and more.
So from a generator's point of view this is easy (and I think also 
more human readable):

start stuff - headers etc.
 - taxonname 1
  - interesting facts about taxonname 1
  - publication information about taxonname 1
  - other names related to taxonname 1
- taxonname 2
 - interesting facts about taxonname 2
 - publication information about taxonname 2
 - other names related to taxonname 2
end stuff

whereas this is hard (but not impossible):

start stuff
 - taxonname 1
   - interesting facts about taxonname 1
   - taxonname 1 published in reference 1
   - taxonname 1 related to taxonname 3
- taxonname 2 
   - interesting facts about taxonname 2
   - taxonname 2 published in reference 2
   - taxonname 2 related to taxonname 4
 - taxonname 3
   - interesting facts about taxonname 3
   - taxonname 3 published in reference 3
- taxonname 4
   - interesting facts about taxonname 4
   - taxonname 4 published in reference 4
- reference 1
  - details for reference 1
- reference 2
  - details for reference 2
- reference 3
  - details for reference 3
- reference 4
  - details for reference 4
end stuff


Of course it may be we're not generating the data in the most 
efficient way ...

ps my vote would be for NomenclaturalCode. Does exactly what it says 
on the tin...
Sally

*** Sally Hinchcliffe
*** Computer section, Royal Botanic Gardens, Kew
*** tel: +44 (0)20 8332 5708
*** S.Hinchcliffe at rbgkew.org.uk



More information about the Tcs-lc mailing list