[Gridflow-dev] work on documentation

[Mathieu Bouchard]

On Fri, 31 Dec 2004, Alexandre Castonguay wrote:

> Stephanie, Normand and I are working on updating the documentation...
> I suggest using the following directories for the icons :
> The 'format' icons can go into /doc/images/format 

yes

> The help screen captures can go in /doc/images/help

i'm not sure about this one yet. i think it may be a good idea to sync the
directory structure of:

  1. pd_help/
  2. doc/images/ (icons)
  3. doc/images/help/

the fact that (3) is placed inside (2) looks a bit weird to me.

actually, now that GF is relieved from the jmax<->pd personality split,
and since the name of almost all help files are changing, and that the
official help file naming policy of pd has changed (in 2003?), maybe it's
time for a big overhaul of the structure (d'une pierre trois coups!).

Here's an example of how I would like it:

  doc/flow_objects/#for-help.pd
  doc/flow_objects/#for-help.png
  doc/images/flow_objects/#for.png
  doc/format/videodev-help.pd
  doc/format/videodev-help.png
  doc/images/format/videodev.png

Let me explain what is changing:

  1. the official suffix of pd help files is changing
     from ".pd" to "-help.pd", and we're a bit late following
     the flock, and now's a good time to do it.

  2. the new help screenshots are going side-to-side with the
     help patches with "-help.png" suffixes so that it's very
     easy to find a screenshot from a patch and viceversa. the help
     files are considered documentation so they go in doc/.

Also I'm pondering whether I'd change the location of the icons again so
that they are also side-to-side with the help files and thus we'd have a
really consistent scheme for placing files, but since Stéphanie just
committed those icons elsewhere, let's just call it "too late for another
change"... I don't want to inflict boring jobs on others...

Anyway, for now, just follow the example above, with icons in images/ and
help screenshots _not_ in images/ (really)...

> A lot of the /gridflow/pd_help files have been updated for 0.7.7 but
> they need to be adapted for 0.7.8.  Maybe matju can check them out to
> okay them before screenshots are made?

Well, I think you guys/gals could update them help files, I'd verify the
changes and approve, and then you'd make the screenshots.

I think the "op" message should be used in the [#] help because currently
it looks very repetitive. That's an occasion to learn about that new
feature of GridFlow. Sending a "op *" to a [# +] will make it behave like
a [# *] but will make it save back as [# +]... nice, eh?

That means there could be just one [#] box in that patch, and the user
would pick the operator they want to try by clicking one of fortysomething
messageboxes.

There are other classes that support "op" (and sometimes "fold"). for
example

"2 3 5 7" -> [#inner ( 10 20 30 40 )] = 2*10 + 3*20 + 5*30 + 7*40

but sending "op &, fold ^" will make it behave as:

"2 3 5 7" -> [#inner ( 10 20 30 40 )] = 2&10 ^ 3&20 ^ 5&30 ^ 7*40

That could go in the help files...

And yes, that's an undocumented feature, and the manual is outdated, and
even the ChangeLog is outdated (i'm not too systematic with it so i forgot
to write down things), so I guess it's time for me to make moulinette.rb
do something it was supposed to do from the start: hunt for
undocumented/misdocumented features and report warnings (just like it does
for missing icons today).

_____________________________________________________________________
Mathieu Bouchard -=- Montréal QC Canada -=- http://artengine.ca/matju