@lacuna said:

Just yesterday I was looking up the equations for waveforms in sinesum, knowing I can find them there.

Derek got that from me from my Live Electronics Tutorial, they're there too you can also find them here https://github.com/porres/Live-Electronics-Tutorial/tree/v1.0-beta-40/Examples/Part.03-Sound.Generators/12-Oscillators/1.Waveforms

@lacuna said:

I don't agree with, people don't touching Extended today, as many patches/contributions are made with/for it, those aren't maintained nor rewritten.

I never said that

Folks, we're on a roll debating all things related to Pd documentation here and there and I'm now focusing on the Pd FLOSS Manuals issue.

Pd has this very famous and long lasting FLOSS Manual. It's old and it tells you how to instal Pd Extended 0.39! So, it's from the extended era and still references to 'extended objects'. For what I see, it was a Manual that came to be in the Extended era as a Manual to it. Back in the day we basically all used just Extended anyway and were mostly oblivious to Pd Vanilla and its manual.

And by Pd's manual, I mean http://msp.ucsd.edu/Pd_documentation/index.htm - I know that's called 'Pd Documentation', and that it is confusing, cause it actually is an 'html Manual' and it refers to itself as "this html manual". Anyway, this is also something I brought up on github and is not the issue here..  
The point is that there's a conflict and I guess this made sense then, but it's a problem nowadays. A documentation noise problem. Lots of people seem to get to it and consider it "the manual for Pd". We're still struggling with a post Pd Extended issue and what was consolidated in its era but now sits as ruins. Actually, Pd Vanilla's manual also refers to FLOSS Manuals. But these days we have something weird, which is simply the fact that Pure Data has these two manuals. One is the official one, included as part of Pd Vanilla and its documentation, and this other one, which is terribly outdated and actually refers to this unsupported and abandoned fork of Pd.

But the point is, one software cannot have two concurring Manuals, even if both are up to date - that'd be silly. The point of FLOSS is to provide the one and only official and single Manual for a piece of software. See the problem? Csound uses FLOSS Manuals as a place to provide its official manual. It's clearly linked in csound.com. Csound also has the 'Canonical Csound reference manual', which is actually something else and not to be confused with "The" manual they provide in FLOSS.

So, my point is we have to get rid of one of them and have a single official one.

Should we then remove the included and official manual from Pd and 'move it' to FLOSS and completely overhaul that online version?

Or just get rid of the FLOSS version? Well, that is there, and people know it. Burn it down, purge and disappear with it would be bad.

Well, I don't know, so I'm asking...

Another scenario is that FLOSS can still be around, of course, but as a museum piece, for those interested in web archeology, as extended is now an archeological piece of software. No one touches it, it stays there, but we try to make it clear how that is an old, outdated, unofficial and that Pd has its own 'real manual. This would help a lot. Or... also, treat it for what it is, a manual reference for Pd Extended, not Vanilla, and make it clear how Pd Extended is abandoned and so is this manual.

Other than these, the only option I see is we maintain and update these two manuals somehow. And I already said how I think that's pointless. I also don't know who'd do that... but maybe there'd be a way to manage them as two clearly distinct guides. One would be the 'Canonical Vanilla Manual' and the other could be 'The Pure Data Manual' (or some other name)? The question would be, why to do that? What is the advantage in keeping another FLOSS version around?

The thing I can think people like about the FLOSS version is:

• A: A friendlier look for beginners;
• B: A nice beginner level tutorial;
• C: Support for many externals, external libraries, how to use Arduino and stuff (more as a tutorial than a 'manual');

These can all be compensated. With 'A)', we can try and make the Pd manual look nicer maybe? As for the rest, what really seems to be the substance of this is the fact that it serves as a tutorial.

Well, a tutorial is not necessarily a "Manual".

We can add tutorials to Vanilla too... actually, even though it's based on Extended, many of the examples there are 'vanilla', so they can be easily ported and shipped as part of Vanilla!

As for tutorials that use externals. Well, they would really benefit from an update. But a tutorial is a tutorial, this could live somewhere else.

By the way, tutorials can easily be uploaded to deken and be available from there. You'd have a tutorial that relies on externals, but that's ok too (my live electronics tutorial comes as part of the ELSE download)... just give instructions in the tutorial on how to install the needed libraries from deken as well...

But if the case is made that we should really keep FLOSS and update it. Well, maybe we could manage and do that, taking care on how to not overlap even know I don't know who'd do it, but it'd mean completely rewrite from scratch and get rid of some of the stuff. That's bad too, as the old version would be lost (so have it sit as an 'old extended manual'?).

So, in short, possible scenarios include:

1. Forget about floss, tell it's outdated (rename it to pd extended manual maybe), focus on Vanilla's manual. Bring stuff we miss and like from FLOSS to current Pd in some new form.
2. 'Move' Pd's manual to a new FLOSS incarnation
3. Keep and manage two versions

My thoughts on these are here, and I think the best scenario is number "1)"

Any other thoughts?

Cheers

@porres said in Contribute to better Pd Documentation:

On the other hand. If you want a new tutorial like the FLOSS one for 'vanilla' as part of its official documentation, then we need to work on it from scratch, and there'll be no need for a FLOSS version that lives in flossmanuals.net! And I think that can easily be included as part of the Pd Vanilla distribution and its online documentation.

So, went to have a look as to what would it take to make the FLOSS tutorials ported to vanilla... and... well, it seems that despite using Extended, some of the examples are pretty much 'vanilla friendly' (no externals). These can be easily ported then...

But where are the authors these days? I know Derek Holzer is one, but he was just recently sayin on the facebook group that the FLOSS manuals is old should be forgotten himself... If we were to update it in the web, who would do it? And could we revise it and change it and take or put stuff?

Well, I'm thinking about copying the basic tutorials here into a new one, fully vanilla, to be downloadable via deken. But... I guess it'll be kinda "based on this", because I have a few issues with some of the things we have here.

For instance, [phasor~] is described as an osccllator, and it is not one in the sense you can plug it in and listen to it as it has a DC Offset. I will suggest that we even change the description in the help object from 'sawtooth' generator to 'phase ramp' generator. Oscillators need to go from -1 to 1. The square oscillator there is also a pulse train instead. And these are not band limited oscillators (so pretty bad and aliased ones) and we should say that...

Also, in ampplitude modulation, I don;t think it's a good classical example to modulate it to a phasor~ signal, an [osc~] should be much better. And the 'tremolo' effect should also have a 'depth' parameter so it can be called an actual tremolo. A tremolo is not just amplitude modulation with a low frequency.

So if I were to design a new and quick, simple, new tutorial for newcomers, I know I'd change a lot of things... so the problem I have with it is not that it's just old and outdated, but also with the content, which I think can be greatly improved.

I created a new issue on github https://github.com/pure-data/pure-data/issues/1331#issuecomment-850893517

Oh, but FLOSS manuals has a nice tutorial for begginers...

Well, there are lots of tutorials out there...

This tutorial is based on Extended and is very very old and misses many new stuff

If you think we should also have a new tutorial to replace this, well, it needs to be a tutorial based on Purr Data, I guess, which is the alternative to extended these days. So, well, not related to Pd itself, but a fork of Pd... but that's a separate project, a Purr Data project. Unlike Extended, the gap from vanilla to Purr is huge and it's just hard to work on something that's suitable for both. As a community, we should also make things like that clear to avoid noise.

On the other hand. If you want a new tutorial like the FLOSS one for 'vanilla' as part of its official documentation, then we need to work on it from scratch, and there'll be no need for a FLOSS version that lives in flossmanuals.net! And I think that can easily be included as part of the Pd Vanilla distribution and its online documentation.

If you're actually unhappy with a 'all and pure vanilla distribution', meaning, you use Pd Vanilla, but you have dozens of external libraries and can't live without them, then we have another issue. How to work with a tutorial that uses some of the external libraries out there? What libraries are worth using? Which are abandoned? How are we gonna have a tutorial inside vanilla that uses external libraries?

I think this can be done too... well... in fact, I have one tutorial myself, and it only needs one single library called ELSE... and it actually comes as part of ELSE. And you don't need to do anything else other than just using deken to download it and use it...

See? How easier could it be? Anyone can design a new tutorial that uses externals and just give instructions on how to download them via deken and use it. We can point to these as part of the OFFICIAL Pd documentation and just forget about FLOSS...

@whale-av said:

The doc for extended was 9.32Mb..... but included 5.96Mb of media.
The doc for vanilla 0.51.3 is 2.85Mb
A difference of 0.5Mb-ish without the media...... so quite a lot of text.

but are you counting the help files of dozens of libraries it had?

Maybe adding a "Documentation" link to the console help menu would be a good first move....?

Hmmm, but there's already a link to a Pd documentation in html right there in the help tab, and we also have the browser which has the same manual section and other sections. Why do we need it in the console?

The doc subfolder names are not enticing..... "3.audio.examples" really could be "3.digital.audio.tutorial" for example

that's actually the examples from Miller Puckette's book and they should be read alongside his book

I don't think there is even a link to it in the "HTML Manual" which becomes "PD Documentation" when it is opened.

No, it's a separate thing, it's not part of pd's documentation per se.... it's something else (the book's examples) that comes as part of Pd.

All very confusing though as the Pd.doc folder is mostly a patching tutorial that complements the Floss manual.

I don;t know why you call this the 'Pd doc' folder, it's the control examples, and yeah, it's like a quick start tutorial, also by Miller.

As a Puredata teacher in a fine art school since 10years (and many workshops in China) the only solution for me to make pd "usable" by my students, was to distributed my own puredata version modified with translated help files from an "computer-scientist" to an "artist" point of view, and with many extra things.

@whale-av said:

Maybe adding a "Documentation" link to the console help menu would be a good first move....?

I agree, if only clickable link could be added to console.

The doc subfolder names are not enticing..... "3.audio.examples" really could be "3.digital.audio.tutorial" for example.
I don't think there is even a link to it in the "HTML Manual" which becomes "PD Documentation" when it is opened.
All very confusing though as the Pd.doc folder is mostly a patching tutorial that complements the Floss manual.

I agree, the documentation could a bit more explicit and well organised. I simply don't use it and added mine.

Finally, Here is an example of my pd version that I throw to students now to have a chance to keep them in the game:

• I am using ceammc a lot, and added some objets and a simple theme:
  

• I added a template for every new patches and some personnal icons to ceammc bar:
  

• Here is my Intro-help.pd (accessible from any right clic in a patch)
  

• I added my own fast prototyping ofelia abstractions:
  

• The right click show all the objects (also have auto-completion of course)
  

I think right-click on objects should propose "Online Reference" that lead to an online up-to-date documentation... or wiki.

@emviveros It could save you a lot of time if you start from the doc folder of Pd extended.
At the time of its release it had already been extensively improved when compared even to the current Vanilla doc.
Some objects will be missing of course but they can be trawled from Vanilla doc/help files.
The doc for extended was 9.32Mb..... but included 5.96Mb of media.
The doc for vanilla 0.51.3 is 2.85Mb
A difference of 0.5Mb-ish without the media...... so quite a lot of text.

It is a great idea and should be useful to everyone.
Unfortunately so many people never see the doc folder though except when they access vanilla help files and even then are blissfully unaware of its existence.

Maybe adding a "Documentation" link to the console help menu would be a good first move....?
The doc subfolder names are not enticing..... "3.audio.examples" really could be "3.digital.audio.tutorial" for example.
I don't think there is even a link to it in the "HTML Manual" which becomes "PD Documentation" when it is opened.
All very confusing though as the Pd.doc folder is mostly a patching tutorial that complements the Floss manual.

You have probably seen that @beem is working on a wiki..... https://forum.pdpatchrepo.info/topic/13054/starting-a-pure-data-wiki-database-examples-collection

Hyperlinks are the past and the future and the object help files in extended had quite a few...... although many are now dead.
David.

ELSE 1.0 Beta 30 with live electronics tutorial is out! This needs Pd 0.51-1 and the highlight is a new abstraction called [batch.rec~] that records your patches into a sound file in batch mode. In this way you can render whatever amount of audio as fast as possible in your computer. This is possible with the new 'fast-forward' message to Pd, available in Pd 0.51-1. The cool thing about this object is that it has multichannel support.

You can download it directly via "Pd => Find Externals", just search for 'else'! Note that the "Live Electronics Tutorial" is part of the package (it relies on the ELSE library). Find the "Live Electronics Tutorial" folder inside the 'else' folder. The tutorial also provides an example on how to use this new 'fast-forward' feature. Check "Vol.1/Introduction-Pd.Quickstart/2.Syntax/4.fast-forward.pd".

Find detailed changelogs at:

• https://github.com/porres/pd-else/releases/tag/v1.0-beta30
• https://github.com/porres/Live-Electronics-Tutorial/releases/tag/v1.0-beta-30

Hi. It is good to be looking at PD again. This time around I am using a Mac or a PC to learn how to program PD. It is simpler than making sure all the settings are correct with an RPi.

I am having a problem with getting a table to read correctly. The example is from a YT tutorial for a beginner but it is from 2007. It might not work that way anymore. The rest of the tutorial works well enough until I get to the point in the tutorial: 6:30 where the cursor is moving up and down, changing the values in one box to alter the values in a another box.

Video:

Beginner's Puredata Tutorial PArt 1 of 2
vreahli

Error message in PD main window:
gatom: no method for 'tabread'
first_patch.pd

@4ZZ4 did you try to right-click on objects that you don't understand and opened the corresponding help files? in most cases, the help files contain everything you need to know about object and how it works.... take a look at th help file of [route], it's easy to understand, if you try out the patch and see what it does. regarding th usage of $ variables please read this here: https://booki.flossmanuals.net/pure-data/dataflow-tutorials/dollar-signs.html. [change] only outputs the values reaching it, when they change (so, when it's not the same number as before for example). but thats not all: again - check it's help file and try to play with the object, connet some message boxes with numbers to it's inlet ( for example [1(, [2( ...) and a {print] object to its output and see what getting printed to the console and what happens, when you click one message twice.
the [r chn( sets the midi channel for the [noteout] object... i have to confess, this is not obvious for a beginner: it gets it's value by the message in the maybe2.pd file, which is connected to [loadbang]. the [t b f] or [trigger bang float] cares for, that the addition operation in the [+] object is getting triggered, whenerver one of both inlets receives a value. otherwise, the operation would only be triggered when the "hot inlet" (the left one of [+]) receives a value. voice stealing specifies what happens, if you run out of voices: for ecxample you have a [poly 4 1] -> imagine, you hit a chord on your midi keyboard with 5 keys simultanously -> you run out of voices, because your [poly] is only set to 4 voices (not 5). with the second argument of [poly 4 1] (the 1) you tell poly to begin "overwriting" the oldest voice with the note, that caused running out of voices. sorry for my poor english, i hope you got me. ok, this must be enough for the moment, but you can find all these anwers in the internet or in the help files and the countless pd tutorials out there. please considr making some of these, it will need some time, to learn pd.
ah, and all the infos above come without any warranty!

PS: the "e"-key on my laptop seems to be on strike sometimes!