[PD] [pd META] metadata format WAS: pd 0.43 branch with the new GUI code

[Jonathan Wilkes]

--- On Thu, 8/27/09, Hans-Christoph Steiner <hans at at.or.at> wrote:

> From: Hans-Christoph Steiner <hans at at.or.at>
> Subject: Re: [PD] [pd META] metadata format WAS: pd 0.43 branch with the new GUI code
> To: "Frank Barknecht" <fbar at footils.org>
> Cc: "Pd List" <pd-list at 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