--- On Thu, 8/27/09, Hans-Christoph Steiner hans@at.or.at wrote:
From: Hans-Christoph Steiner hans@at.or.at Subject: Re: [PD] [pd META] metadata format WAS: pd 0.43 branch with the new GUI code To: "Frank Barknecht" fbar@footils.org Cc: "Pd List" pd-list@iem.at Date: Thursday, August 27, 2009, 6:28 PM
On Aug 27, 2009, at 11:04 AM, Frank Barknecht wrote:
Hallo, Hans-Christoph Steiner hat gesagt: // Hans-Christoph
Steiner wrote:
On Aug 27, 2009, at 3:47 AM, Frank Barknecht
wrote:
Hallo, Hans-Christoph Steiner hat gesagt: //
Hans-Christoph Steiner wrote:
How about Outlet0, etc? Its really
just a unique ID, so once parsed
the tag could be displayed as whatever.
Actually I think, "Outlet 0" is easier to
parse with Pd: [route
Outlet]-[route 0 1 2 3]. Having a separator like the ":"
makes reading easier. I
guess, for Pd parsing padding that with spaces would help
and not hinder
readability that much.
[route outlet0 outlet1 outlet2 outlet3]
Okay, you got me here. :)
Can you give some examples of why [pd META] needs
multiple-word tags?
For terms with multiple words like "frequency
modulation". I know, I need them,
believe me.
I know its not perfect, but frequencymodulation and FM work.
I mean its nice sometimes, but there are very well
established tag
interfaces that use space-separated tags.
Since this text is in Pd
patches, it should follow Pd syntax rules, since
Pd users already know
them well, unless there is a strong reason to
diverge. With only a few
exceptions, the function in an object box is the
first word in a
space-separated list. In a message, the
first word of a space-separated
list is the selector.
What's more needed is a quoting mechanism.
Space-separated tags usually
use "two words" quotes to join them. But
that's a bigger issue in Pd...
Yeah, that would solve my problems as well.
But let me repeat: Unlike "META", "REFERENCE" is meant
to be documentation for
the user, so readability is more important than
parsability, and parsability
outside of Pd to us is more important than parsability
inside of Pd. The latter
would be a bonus, but I won't sacrifice readability
for it. We're already
making concessions in that area, e.g. we have single
comments for all the
messages types an inlet accepts. (See "Inlet 1" in the
attachement.) Pd syntax
rules are fine, but English syntax rules where spaces
separate words, not
key:value pairs, are more important here.
I also don't like "Outlet0" of a similar reason: It's
not well readable,
0 and O look too similar etc. so the two words should
be separated just like
everything else in English.
Inlet0/Outlet0 could be somewhat hard to read, but I think context really helps a lot there. I could maybe see someone speaking Spanish or Italian expecting "inleto" or "outleto", but I can't see a reason why anyone would expect there to be InletO or OutletO.
OutletOne, OutletTwo, InletThree is an option, tho not very computery.
Attached is a comparison of the possibilities we've
talked about. I like the
first one best, which probably will get dashes in the
Tags field as a result of
our discussion. The second one in the upper right and
the third one are
okayish, but the "META"-version on the lower right to
me looks like it is
written for parsers, not for humans.
[pd META] was written more for meta data, since it doesn't include things like inlets, outlets, etc. But it was not so much designed to be easily parsed as much as easily written by Pd patchers, yet parsable. The non-meta is on the front page of the documentation rather than in a subpatch. I like the idea of having everything easily parsable, including the reference text.
One thing that bugs me with [pd REFERENCE] that I find very hard to scan is the message types an inlet takes. They are all bunched up into a single comment, making it hard to scan and even read. The same goes with the Gem docs.
I think that if the PDDP template had some of the graphical elements stripped out and a couple of other minor adjustments, I think it could work quite well. I attached my version of it from the 'apple' library. For example, I find big blocks of text hard to scan. And most of the time when looking at a help patch, people are scanning, not reading. I think the layout of the PDDP template, though more work for the creator, makes for very scannable and readable information.
I don't know what the patch you attached has to do with the PDDP template. There aren't any big blocks of text in the PDDP template.
Something to consider in parsing is the possibility of using Y location in the parsing. It would require two pass parsing, since the file is not organized by Y position, but wouldn't be so hard to do in Pd or easier in string parsing languages. This makes the front page format of the PDDP parsable, though getting the inlet/outlet numbers could be a bit tricky. Having the IOlet number markers have horizontal lines would make people naturally put them above the text, making the parsing much easier.
.hc