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.
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
¡El pueblo unido jamás será vencido!