[PD-dev] pddp style guide

[B. Bogart]

Hi Krzysztof,

Perhaps I am missing your mark. Ok so we agree on the centralization of
the PD help patch.

So you see PDDP as a way or organizing multiple types of documents in a
  somewhat unified way. Ok.

If we think of a patch as just a patch that is all that it will ever be.
A patch could be a document as well though. The main problem I see with
having the documentation in different types of media is this linking
back and forth part. Abstract concepts, theory, could be more easily
represented as a large text-document. I'm not sure if this is the case
though, since I personally think theory is best expressed through
concrete real-world examples - patches. It is true that things like
formulae don't work in PD too elegantly, expr being the most clear
representation of an equation, but not all types.

Its the switching back and forth part that makes me wonder about that
approach. With examples embeded in the document the way the person reads
the document leads back and forth between example and theory, without a
mode switch. I can see your idea of linking to static document types
work in the case of extra supplimentry information, details on a lower
level. Stuff that would scare the novice user.

I guess what I'm thinking is that the ideas are expressed more by
example and by experience of the user (as they look at multiple patches)
than by a text. This could be off-base. I may just be getting too
confused between the tutorial workshop project vs the help system.

Ok I'm going to comment inline for the specific issues...

Krzysztof Czaja wrote:
> hi Ben,
<snip>
> Those links should directly point to a detailed description (aka
> reference page, which may actually span several pages), and
> a ``more info'' story (which may contain math formulae, figures,
> etc.)  The story would link back to various example patches and
> tutorials.
>
> It is probably only a dream...
>
> Anyway, I feel sorry jumping in the middle of your discussion like
> some kind of a troll...  I was just staring at the main screen of
> float-help.pd (seemingly an attempt at mimicking Max reference
> pages by the ``uglier-but-smarter sister''), extrapolating it into
> xeq-help.pd, and feeling uneasy about:


> struggling with an unsuitable editor

Unsuitable in terms of text-editing or editing in general? I think any
improvements made to make text-editing easier would also improve the
general patching process?

> representing my content as Pd global symbols and floats

I see two things, the active content bing the PD patch and its messages,
also a text block that is a light overview of theory, not a huge amount
of text. I figure it would be half-and-half, text and patch.

> storing my content as an unstructured set of bits and pieces

Yes this is true. It is interesting that the talk about comments
prepended are actually an effort to structure the comments. What if this
went further? I confess I'm not sure how...

> giving my screen an ugly look

It does take a bit more effort to make a PD patch look good, but
canvases, indentation (using duplicate), and spacing really do help.

> not being able to print my content in any reasonable way

"file -> print" not reasonable enough? What if there was a script that
converted a folder of patches into a single multi-page PDF?

> not being able to publish my content on a web page

About the same anser as above, unless you see a big issue with putting
PDFs on web-pages.

I guess I've made it obvious that I think having the text and example
integrated into once process (document) is the more advantageous. It is
much easier to extend the PD patch format to make nicer documents than
it is to make html and PDFs make nice interactive examples.

I'm thinking the final result would be a combination of both ways, with
links to supplimentry information as html/pdf/etc documents but the most
pertinent information being presented in the patch itself. The latter
being easier and most valuable I would say we start with that and go
from there.

Should the "hyperlink" object be a toxy widget or an external or an
internal? Should it just be part of the [comment] or some new [text]
object? hyperlinks inline with comments/text would be pretty familiar to
people.

What do we all think?

B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
URL: <http://lists.puredata.info/pipermail/pd-dev/attachments/20050505/053deafd/attachment.pgp>