Documentation thread - Any help is most welcome!

[jaffasplaffa]

Hey :)

This issue is dedicated to documenting PlugData and we hope that community is willing to help out!

Documentation includes short descriptions of object functionality, as well as in/output descriptions. The idea is that these description will show when you hover the mouse over objects and in/outputs.

A better and more specific description of the tasks that help is needed for, will be presented soon........

If you feel like helping out, please drop a comment. No coding experience is needed, but the ability to explain something briefly and easy understandable is a great skill to master for such a task :)

Thanks!

[timothyschoen]

There are currently about 200 pddoc files that need documentation, and 3 people that are willing to do it so far (@jaffasplaffa @ludnny and I). How about we start by doing 50 each?

abs (A) - drawtext (D): @jaffasplaffa element (E) - mult~. (M): @timothyschoen neq (N) - rzero~. (R): @ludnny

If anyone else wants to contribute of anyone has more time available, we can start covering the last 50 objects as well.

No pressure btw, take all the time you need or let me know if 50 is too much. I just want to prevent that everyone will start working alphabetically from A ;)

I suggest you submit a pull request, then you'll appear on the page as a contributor.

For anyone who hasn't read about this yet:

https://github.com/timothyschoen/PlugData/tree/main/Resources/pddoc/vanilla

Contains a bunch of xml files that need to have their "inlets", "outlets", and "description" fields filled in, I've attached an example of some finished ones below:

examples.zip

[timothyschoen]

Useful resources:

https://puredata.info/docs/tutorials/pd-refcard

In many help files leads to:

[jaffasplaffa]

I am up for giving it a go :)

About doing pull request, most of the stuff I've done, I did locally and then uploaded to Github, so not really too sure about that side. I will read up on it.

But I am really not an expert on this. I need to be shown, preferable like I was an 8 year old kid, where to put the descriptions.

I think I need to see a couple of already done descriptions, maybe with the descriptions highlighted or in fat text?

Just to make sure I don't waste a lot of out time on doing something the wrong way.

[timothyschoen]

Good idea, I'll provide some very clear instructions soon!

[jaffasplaffa]

Here is what I THINK I need to do. This is the "change" object:

I've highlighted the changes I've made or updated any text that was already there.

[timothyschoen]

Yeah looks good! I'd make some things a bit more brief and start descriptions with a capital letter, like this:

"output only if input changes" -> "Output when input changes"

There's no arguments or methods yet. Maybe it would be nice to cover arguments as well, they could show up in the suggestions box when you've completed typing the name of the object?

Like this: <argument name="Initial Value" type="float" default="0"></argument>

I found this info in the pd reference:

If there's no default in the pd reference, it can be omitted for those objects.

[jaffasplaffa]

Ahh, yes of course I will use the references, I just wanted to be sure I did the right changes.

I will make description shorter and start with capital letter.

For example for the change object it does not take symbols, so I can delete, this right?: symbol input

This is how it looks like now:

Not 100% sure if I got the "set value" correctly?

[timothyschoen]

I'd go with

<xinfo on="set [float]">Set the value</xinfo>

The pd reference says set <float> but that's very confusing in xml documents.

Another exception is objects like sel which have an uncertain number of inlets or outlets. So lets define that idea for our format:

<outlets>
  <outlet  repeating="1">Bang if input machtes argument $1</outlet>
</outlets>

The repeating flag enables this behaviour. The $1 will be replaced with the inlet index.

[jaffasplaffa]

okay so ONLY for the labels with "set" i will do set [float]

instead of just this for the rest

[jaffasplaffa]

I did a Fork of the rep and did the FIRST object, abs: https://github.com/jaffasplaffa/PlugData/blob/main/Resources/pddoc/vanilla/abs.pddoc

Removed arguments, since there are no arguments for that object.

(Sorry for all the questions, I just need to be confident I started properly :) ).

[timothyschoen]

Very nice, and no problem, it's better to make sure you get it right than to do a lot of work only to find out it's useless ;)

Small point is that's I'd make the object description slightly shorter if possible. Just "Absolute value" could maybe do in the case?

I'd like to show them in the suggestions as well, so if it fits, that'd be nice. It's not super important, but still a nice. I'll make the default suggestionbox size bigger as well.

[jaffasplaffa]

Yes I understand, I'll make it shorter. I just used the description from abs~.

Personally I like the descriptions a bit more explanatory, cause I am not a coder, so I am not sure what all of them does. With good description, I can actually understand what the object does, without having to do external research on Google. I think for a lot of people that would be a great help.

But yeah, if it's used elsewhere and need short format, that's what we are gonna do :)

[timothyschoen]

@ludnny I accepted your pull request, but you're not appearing as a contributor yet (which I think would be well deserved), no idea why this is though. Maybe it takes some time to update...

[timothyschoen]

[ludnny]

Waaw! This feature will change everything :)

[timothyschoen]

Yeah I agree, it helps a lot! Especially for objects with a many inlets/outlets it's a huge help. I also think it has some educational value for people who are new to pd. Once we cover ELSE and cyclone as well, it can also help people who aren't familiar with those libraries yet. Maybe @porres could assist with that?

Also, I'm wondering if we need to add a type to the output label? For metro we could have

<outlet out="bang"> Metronome ticks </outlet>

So it'll read "(bang) Metronome ticks". I think that'll be even better. For objects that don't consistently output one type, it can be omitted.

I'm extending the pddoc format with new ideas here a bit, but adding extra attributes shouldn't break compatibility. I'll probably submit everything to the pddoc project when it's done.

[ludnny]

I also think it has some educational value for people who are new to pd.

That could break a huge barrier for begginners, I stopped using PD multiple times because of this barrier.

Also, I'm wondering if we need to add a type to the output label? For metro we could have

<outlet out="bang"> Metronome ticks </outlet>

For signals the type is signal? <outlet out="signal">Signal</outlet>

[timothyschoen]

Yeah exactly!

[timothyschoen]

Sometimes I run into an object that doesn't exist in pd (anymore?), in that case I just remove it.

[ludnny]

Sometimes I run into an object that doesn't exist in pd (anymore?), in that case I just remove it.

Ok, I remove the ones I can't find in Vanilla. (neq...)

For the object or, I assume it's the object || in PureData? Should we remame that ||.pddoc?

[ludnny]

Do you want to encode the flags as well, in addition to the arguments? (for example netsend -u)

What would be the format for that?

[timothyschoen]

good questions, I think "or" is actually "bitwise or" instead of "logical or", since the original description is "bit twiddling". There might still be some missing objects, I don't see a description for logical or, and GUI objects also appear missing.

About flags, I'd add flag="u" so that makes:

<argument name="ARG_NAME" type="symbol" flag="u">-</argument>

I still have to implement args in the UI, but I'll make sure it supports this!

[ludnny]

good questions, I think "or" is actually "bitwise or" instead of "logical or", since the original description is "bit twiddling". There might still be some missing objects, I don't see a description for logical or, and GUI objects also appear missing.

But if I want to do a pddoc for the object ||, how I should call it? As these characters are not allowed for filenames? You link them manually, or based on their names?

[timothyschoen]

I've decided to make the syntax for using inlet index numbers a bit better, I hope it doesn't affect any work you've already done...

$mth -> index of inlet/outlet starting from 0 $nth -> index of inlet/outlet starting from 1 $arg -> object argument with the same index as the inlet/outlet

You can just insert these into any description, and it will be replaced with the correct value.

For example, [expr] looks like this:

        <inlets>
            <inlet repeating="1">
                <xinfo on="float">Replaces $f$nth in expression</xinfo>
                <xinfo on="symbol">Replaces $s$nth in expression</xinfo>
            </inlet>
        </inlets>

which results in:

Note that you can only have 1 repeating argument, otherwise it would be impossible to know which inlets/outlets belong to the descriptions. But I think that more than 1 repeating inlet/outlet never happens in pd?

[timothyschoen]

good questions, I think "or" is actually "bitwise or" instead of "logical or", since the original description is "bit twiddling". There might still be some missing objects, I don't see a description for logical or, and GUI objects also appear missing.

But if I want to do a pddoc for the object ||, how I should call it? As these characters are not allowed for filenames? You link them manually, or based on their names?

The name inside the <object name="||"> will be used, not the filename, so it doesn't really matter. I think calling one file bitor and the other logicor is the most clean solution.

[timothyschoen]

I think flags are still a bit confusing, but if we just make sure they all have an attribute flag at least it will be easy to fix them later.

[ludnny]

For inlets that could receive any type, I used the type anything (this is the type a, used in the pack object).

            <inlet>
                <xinfo on="anything">Anything to send to parent patch</xinfo>
            </inlet>

I'm not sure it's an official type in pd?

Or I could do this:

            <inlet>
                <xinfo on="bang, float, symbol, list">Anything to send to parent patch</xinfo>
            </inlet>

[timothyschoen]

I think anything is fine, for documentation purposes it's at least much cleaner.

[ludnny]

I think there is a problem for outlets in this format. How do you see the difference between 3 outlets, and 2 outlets with one having 2 different types? :

        <outlets>
            <outlet out="symbol">Messages sent from connected netsend objects</outlet>
            <outlet out="float">Number of open connections for TCP connections</outlet>
            <outlet out="symbol">Address and port</outlet>
        </outlets>

It would be more logical to use the same structure as inlets, don't you think?

(here is a fake example to show a situation with 2 outlets, and 3 types) :

        <outlets>
            <outlet>
                <xinfo on="symbol">Messages sent from connected netsend objects</outlet>
                <xinfo on="float">Number of open connections for TCP connections</outlet>
            </outlet>
            <outlet>
                <xinfo on="list">Address and port</outlet>
            </outlet>
        </outlets>

[timothyschoen]

So I've handled it like this:

<outlet out="symbol, float">...</outlet>

But I see that doesn't work here because the types have different meanings... Your solution looks good, let's do that. The only thing is that it says "on" which suggest that it responds to an action, maybe change that to "out". I'm gonna have to redo some objects ;)