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

@jyg said:

@60hz said:

If it is possible to edit flossmanuals, I would suggest to keep it, removing obsolete part and modify all references from pd-extended to Purr data since it is a replacement of it?

Yes. Indeed, I started unilateraly to edit french version of floss manual
https://fr.flossmanuals.net/puredata/quelles-sont-les-differentes-versions-de-pure-data/

It seems @60hz proposed to turn the current Floss Manual into a Purr Data manual - the thing some of us are opposing to in here. Is this what you started to do unilaterally in one of the translations?

By the way, how can one get involved and start editing the english version (unilaterally or not?)

IMHO instead to change everything in one shot (that causes a lot of never-ending threads) just try to stick to a pragmatic step-by-step policy. First improve what's depend of Pd-vanilla ownership. The FLOSS manual was a great community documentation, and it should be updated, but that task is out of scope.

Let people maintains their work, maintain yours first.

1. Renovate the help / tutorials patches (it took me three monthes for Spaghettis).
2. Achieve the Pd translations (i mean the software itself) if not.
3. Create GitHub pages for a new fresh documentation (make it translation friendly).
4. Link the app to it if required (personnally i don't like html help pages in App, but it seems everybody likes!).

My 2 cents (again).

(((Of course my POV is very GitHub based, and i'm pretty sure it could be also debated!)))

@60hz said:

So what I see is that pd-vanilla and his minimal gui with computer scientists oriented documentation is not suited for newcomers and artist but purr-data is. So that should make sense that flossmanuals should have a documentation about it.

It makes sense and we're saying Purr Data can have its own Floss manuals, but what are you talking about, a new entry or turning the current Floss Manuals into a Purr Data Manual?

By the way, the point of updating this Floss manuals to Vanilla is to make its documentation and itself more suited for newcomers, the solution to the exact problem you're raising it won't change if we don't do anything about it and if efforts to change it are rejected.

Folks, when I started this thread, I made no mention to Purr Data. Purr Data is something else. I get the confusion, I get the relation, it's not out of purpose to bring this up here, but I want to make things clear.

See, we're talking about a Manual, a so called "Pure Data" manual, which actually mixed the notion of Pd itself and Pd Extended (now dead) and sits around still as a "Pure Data" manual. While Pd itself has also its 'official' manual. That's all very confusing already, right? The point is then to fix this, work on the Pure Data documentation itself (it's all in the original post). Purr Data relates to Pd and Extended but it's a whole different animal. It has different configurations, interface, features and whatnot. More over, it has quite strong incompatibilities that people don't seem to bring up. When you have a so called Pure Data manual talking now about 'Purr Data' actually, things get even more confusing, we're adding more noise.

What's also confusing is the mixed notion of a 'Software Manual' and a 'Tutorial'. These are supposed to be distinct things. And tutorials are free to focus on different things. Floss seems to be a tutorial on how to do some stuff in Pd, not a 'real software manual' at all. Floss also seems to be good to talk about some externals for Pd. Cool... we could update it then and keep it mostly the same. The changes would be minimal. We'd have a good section on how to manage externals in Pd Vanilla theses days. That'd be great, right? How to configure, etc...

If you're saying, "but hey, I think most of the tutorial examples would work on Purr Data, as they already ship the externals we're talking about, cause they were originally based in Extended", fine! Cool! Great, we can see if what we have in the end perfectly suits being just implemented, opened, and used in Purr Data as well. I'm not talking about the configuration part and things like that, just running the patches...

If it's all fine we can just say "hey, the things you see here are also suited if you want to run Purr Data"

How about it?

Note: On the other side, I prefer using pd-ceammc libraries which are organized AND replace all pd-extended and more, so the best would be having Purr Data + ceammc lib and the peace would come back on earth...

They do not, by far, replace "all pd-extended", nope, sorry, not a fact. Where's ceammc's GEM replacement for instance?

And what are you suggesting with "Purr Data + ceammc lib"? A Floss manuals for both?

And are you talking about the ceammc library that you can install directly from vanilla and use it as part of vanilla or the 'Pd-ceammc' fork of Pd, that comes with the ceammc library and some more stuff?

Well... everything I said about "hey what about Purr Data?" applies here. And the fact is that Pd-ceammc, unlike Purr Data, is not a "whole different animal", it's pretty much just another 'race' of Pd. It is 100% compatible to Pd-Vanilla (unlike Purr Data). the changes are minimal. You can, for example, run Deken and install externals in Pd-ceammc.

If you don't want to bother using something else than Vanilla, you can install the ceammc library in Vanilla and just use most of what ceammc offers anyway. It's all compatible.

So any Pure Data Manual, Floss manual, tutorial, will work great for Pd-ceammc. And if we consider the fact that a Manual for Purr is needed (not a tutorial, a 'manual', a 'software manual') since it's just too different. That doesn't hold for Pd-ceammc.

And yeah, when I say Purr Data is highly incompatible, you can't run any of the GUI objects from Pd-ceammc in Purr Data. You can't run other GUIs from other libraries.

In fact, Purr Data doesn't even have all of the GUI externals from extended ported and running. Also, Purr Data misses updates from cyclone. Purr is also not doing a great job keeping up to the latest vanilla changes and has some changes of their own to vanilla things. So, unlike Extended and Vanilla, it's really hard tying them with a knot. Unfortunately, at least to me, the community is divided. There are independent developments. And it's hard to manage this, hence the talk about creating a whole new FLOSS for them if needed.

If Purr Data were in fact a reincarnation of Extended, fine. But that's not quite it. And here's something people don't really seem to be aware is that the best shot to have an updated external library that runs all extended patches is going to be "Vanilla + install externals yourself"

And there's also the fact that there are more libraries than just the extended libraries out there, and you can also get them into Vanilla. Like ceammc, like timbreid, like soundhack, like ELSE, like many many others that are just missing, not compatible or hard to get into Purr.

So, there's a way to have both Pd-ceamm + Purr Data when it comes to the externals - get them all for vanilla!

Sure, you'll miss the interface differences from Purr and maybe I don't know what. But that's it, and it needs to be clear what the choice is, there's also a sacrifice in giving up Vanilla.

@60hz said:

Note: On the other side, I prefer using pd-ceammc libraries which are organized AND replace all pd-extended and more, so the best would be having Purr Data + ceammc lib and the peace would come back on earth...

By the way, my ELSE library was meant as a replacement for Extended as well, at least for my needs and my live electronics tutorial (with over 420 examples now and counting), this tutorial is part of ELSE in its download. ELSE provides more than 420 objects and replaces ALL the ones from extended that I used and also the new ones I created for recent Cyclone. It also offers a lot more stuff that was never in Extended.

You can download ELSE as part of Pd-ceammc via their deken and all, use it, 100% comptible too. Or you can have both ceammc_lib and ELSE in Vanilla (and more of the extended libraries you miss. You can't fully run neither ceammc nor ELSE in Purr.

So, yeah, my point is, there's life beyond extended. If people get out of this cave, free themselves from these shackles, just get over it, we can move on. We can make an up to date Floss Manuals that actually talks about these things, we can update the resources in puredata.info (there's not even a mention about pd-ceammc there).

The solution is hard, time consuming, but simple: update, update, update. This is here already, but people are unaware, so we fix this by spreading the word, by doing all that it takes.

Otherwise, we'll live in the past and be eternal widows of Extended and keep saying Vanilla is obscure, less accessible. Well, I wanna just change that.

@Nicolas-Danet said:

The FLOSS manual was a great community documentation, and it should be updated, but that task is out of scope. Let people maintains their work, maintain yours first.

Prize question: do we still have FLOSS maintainers out there? If so? Where are they? One way or another, how to update it, if we're doing it? I'm still unaware. I did contribute a bit to the project back in the day, in 2009. My name is there, I worked with Derek, who's now off the ship. I wanna know what it takes and what to do about it

Anyway, I see what you mean, and it makes sense, for reasonable people. I guess I'm not I do byte on more than I can chew and I already have a lot on my plate. Call me crazy, but I've been managing some insane things well and have achieved them, and I'm now considering this ludicrous undertake to overhaul Pd's documentation, all at one shot. Including the Floss Manual. Let's see...

@Nicolas-Danet said:

Renovate the help / tutorials patches (it took me three monthes for Spaghettis).

where's this by the way?

@jyg said:

Yes. Indeed, I started unilateraly to edit french version of floss manual
https://fr.flossmanuals.net/puredata/quelles-sont-les-differentes-versions-de-pure-data/

Great! I might help when I'll have time!

@porres said:

They do not, by far, replace "all pd-extended", nope, sorry, not a fact. Where's ceammc's GEM replacement for instance?

True. That's another topic, but I am using ofelia abstractions to replace Gem in puredata vanilla and ceammc lib. I think efforts for video processing on pd should be focused on it in the future since Gem is always broken on OSX and openframeworks is stil an active project.

@porres said:

And what are you suggesting with "Purr Data + ceammc lib"? A Floss manuals for both?

I was just dreaming that one day the modern GUI of Purr Data could meet the good organization of ceammc-lib,

@porres said:

Folks, when I started this thread, I made no mention to Purr Data. Purr Data is something else. I get the confusion, I get the relation, it's not out of purpose to bring this up here, but I want to make things clear.

I just thought that the actual old extended could be re-usable (movable?) to a Purr data specific flossmanuals and not completly thrown away...

I agree with making flossmanuals a PureData (pd-vanilla) compatible manual. I just pointed out that flossmanuals PureData could be written in a more accessible way than pd-manuals itself, and could include some externals like else or ceammc later for exemple.
ceammc lib is handy and too few people know it for exemple. It allows me to make my last workshops less confusing by using a great and exhaustive set of objets grouped by their function and they really "simplify the learning process and makes the language itself more clear."

@porres So... and you seem up for it..... let's have a better Pure Data Vanilla manual...... start with that and leave the rest for later.

Terminology...?
Will you adopt "manual" in preference to "Documentation"?
Will you stress (emphasise) "VANILLA" so that it is recognised and understood by new users?...
...... "Pure Data Vanilla Manual"....?..... "Pure Data - The Core - Vanilla"..... "The beating heart of `Pure Data - Vanilla"........."Pure Data Vanilla - The Matrix" ......:

"Pure Data Vanilla is the core.... the "operating system" of Pure Data".
And then introduce externals and Deken at the very start of the manual (before the current Chapters 1 and 2) so that new users stay concentrated on Vanilla as they progress......knowing that the other stuff is "extra" and exactly what that means.
No details will be required at that point... just one sentence and a link to the workings of Deken in a later chapter.

Once that is achieved the same few sentences from the start of the new Vanilla manual need to be added to the start of every other manual and tutorial that exists on the web......... if that is possible.

Would "Core" or some other word actually be better than "Vanilla"?
It has a meaning that is slightly obscure in modern English.
Google is not enthusiastic...... and brown paper envelopes are a rarity nowadays.......
"Synonyms & Antonyms of vanilla · beige, · characterless, · faceless, · featureless, · indistinctive, · neutral, · noncommittal, · nondescript."
David.

@lacuna said:

(I would also recommend learning Vanilla first and start using other libs once you know basic vanilla-vocabulary.
...right click on the blank canvas > help , shows all vanilla objects...
Else you might be browsing huge lists of ojects of many libs for each problem to solve, instead of finding the solution by thinking in Vanilla, with it's limits in mind. )

I remember learning PD-Extended as beginner, and the crowded "extra" folder was overwhelming, as downsides:
There were libs for very specific tasks, that I never would have thought of (and get distracted by), different objects doing the same or almost the same, objects, that can be build with 3 Vanilla-objects, different authors with different terminology, design- and documentation-philosophies, ect.

The learning curve was steep, but in that time I thought Vanilla would be lame and only being used for embedded projects or by purists.

The death of Extended was a great loss, but later a revelation to me:
You can do "everything" (ok, not really) with Vanilla while the vocabulary is small.
And Vanilla is small enough to last, to get bug fixes, and run stable.

@whale-av said:

and brown paper envelopes are a rarity nowadays.......

You are confusing "manila" and "vanilla." Manila is a fiber like hemp which is used to make various things and they all end up that sort of brown color. Vanilla in this use just means plain and unadorned, like plain old vanilla ice cream with no toppings. Fairly common usage, at least in the US.

Edit; That was somewhat pointless and pedantic. Seemed very relevant and on topic while I was waiting for my coffee to brew.

If we talking about naming conventions, it should clearly be named "External Manager", not "Deken"

Anyone knows who 'mickfuzz' is? => https://en.flossmanuals.net/pure-data/_info/

just emailed him

and why do we have an archived version of the manua that is just the same here => http://archive.flossmanuals.net/pure-data/ ?

And why is the manual in different languages different? https://fr.flossmanuals.net/puredata/introduction/

Is it cause we just have total chaos, mess, and independent unofficial takes on what a Pd manual is and should be? and depending on what language you speak you get a different idea and information?

@porres From what I understand when the manual reaches a state where the authors feel it is done it is published as a pdf on www.flossmanuals.net and can be downloaded or bought as print on demand, the web version is then archived at the archive.flossmanual.net address. The version at write.flossmanuals.net is a new version which was opened to continue developing the next edition, but it was never worked on after the first version was published. To sign up for working on it you fill out the form at https://www.flossmanuals.org/get-involved-0, I applied for access on Saturday but have yet to hear back.

So I think new Pure Data Floss requires:

1. a new intro
   1.1 Pd creation history
   1.2 Pd forks and Vanilla externals
2. Update Tutorials keeping externals

something more?

@porres

where's this by the way?

There: < https://github.com/Spaghettis/Tools >.

But as it is just for my fork, that's not compatible anymore with Pd.

Note that it was a very painfull experience to "clean" the Puckette patches.
For me the official manual of Pd is the Puckette book.
That's why all the tutorials can not be changed easily (i.e. without changing the book also).

@Nicolas-Danet said:

But as it is just for my fork, that's not compatible anymore with Pd.

so how can I see what you did?

Note that it was a very painfull experience to "clean" the Puckette patches.

I don't know what you did and when, but recently I also "cleaned" them up and the result is already there in the latest version. I guess my OCD makes me a good candidate for this kind of work... it took me a week, but it wasn't painful

cheers

@oid said:

To sign up for working on it you fill out the form at https://www.flossmanuals.org/get-involved-0, I applied for access on Saturday but have yet to hear back.

I applied on monday, nothing yet here, what about there?

@porres Same, no response yet.

@porres

so how can I see what you did?

Build Spaghettis!

Notice that since i'm currently working on a new version with JUCE the current version can be considered absolutely WIP.

@emviveros said:

a new intro
1.1 Pd creation history
1.2 Pd forks and Vanilla externals
Update Tutorials keeping externals
something more?

Maybe useful plugins like drag&drop, completion, patcherize...
Some of them are so useful that they should be inside vanilla pure-data.