discussion about working on .md files for online reference

[porres]

previous discussion in #46

[Lucarda]

This is a change to the format we made for plugdata, since we use these docs to provide tooltips. Putting all the methods inside the tooltip would be too much. (porres already knew that but in case anyone else is wondering)

@timothyschoen so IIUC these information you added is only on UI objects? (the ones https://pd.iem.sh does not cover yet).

there are lots of chances that we all benefit from using https://github.com/pd-projects/hugo-puredata.info as the central place for objects .md files.

[timothyschoen]

I agree it would be better if we used the same docs, it saves us some doing the same thing twice. There are a few changes made to the docs, @tomara-x and @vasilymilovidov know more about this, but basically:

1. We have separate sections for object methods and regular object messages
2. Some descriptions have been shortened to better fit a tooltip
3. Some descriptions have been improved in general
4. We also have descriptions for all GUI objects

The first problem is solvable, I have a python script that parses all the docs here, you could also use this to combine methods with inlet messages again, and make any other necessary format changes. I've just started working on a system for this anyway, so I can use your website generator to create online docs for ELSE and cyclone.

So other than that, whether we can use a single format really depends on whether you're okay with the changes we've made or not.

[tomara-x]

hehe you summarized it perfectly :3
two more things to keep in mind:

• we have our own categories that are the same across vanilla, else, cyclone, and heavylib objects
• notice that first "vanilla" category (we added those to filter-by-creator in the object browser)

[umlaeute]

notice that first "vanilla" category (we added those to filter-by-creator in the object browser)

i would very much prefer if the term vanilla would be replaced by Pure Data (cf. Pd's "Help Browser").

[umlaeute]

also I'm not entirely sure whether Pure Data (or vanilla) should actually be a pdcategory, or rather some scalar property origin (or similar).

[timothyschoen]

also I'm not entirely sure whether Pure Data (or vanilla) should actually be a pdcategory, or rather some scalar property origin (or similar).

I agree with this, we should change that

[umlaeute]

what is the reason for separating methods from messages to the 1st inlet?

[umlaeute]

i think the combined types (e.g. float/list) should go away.

instead people should learn that a list 3.14 can be used as a replacement for float 3.14 (and I don't think that the tooltips are the right place to teach this)

[umlaeute]

while i still haven't checked any help with a combined type, i think this confusion is related to #142

[porres]

Maybe something in else, I dunno... I'd like to see some examples cause maybe we need to revise it indeed

[tomara-x]

quick grep found this: (there could be other combinations i haven't tried)

float/symbol

ELSE/clock.md
ELSE/format.md
ELSE/iterate.md
ELSE/note2dur.md
ELSE/replace.md
ELSE/route2.md
cyclone/capture.md
cyclone/coll.md
cyclone/cycle.md
cyclone/iter.md
cyclone/spray.md
cyclone/sprintf.md
cyclone/substitute.md
vanilla/get.md
vanilla/makefilename.md
vanilla/pack.md
vanilla/pipe.md
vanilla/plot.md
vanilla/route.md
vanilla/select.md
vanilla/set.md
vanilla/unpack.md

float/list

ELSE/ceil.md
ELSE/cents2ratio.md
ELSE/dec2hex.md
ELSE/floor.md
ELSE/fold.md
ELSE/hz2rad.md
ELSE/op.md
ELSE/pitch2note.md
ELSE/rad2hz.md
ELSE/ratio2cents.md
ELSE/rescale.md
ELSE/rint.md
ELSE/trunc.md
ELSE/wrap2.md
cyclone/atodb.md
cyclone/click~.md
cyclone/clip.md
cyclone/dbtoa.md
cyclone/past.md
cyclone/pong.md
cyclone/round.md
cyclone/scale.md
cyclone/thresh.md

[porres]

Yeah I need to revise those dates n cyclone and else. Should be just list! Thanks iohanness

[umlaeute]

what I would really like to have is to actually be able to pull all that information from the help-patches themselves (that is: generate the markdown from foo-help.pd; the front-matter is practically the same as what we have in [pd reference]).

[timothyschoen]

I would have liked that as well, but for us it wasn't an option, since we need to support helpfiles for pure-data, ELSE, cyclone and heavylib, and it would already be very difficult to write something that consistently produces correct output.

[umlaeute]

well yes; obviously a problem if you want to have things work right now.
i'm usually not so much concerned about that 😜

[umlaeute]

also note, that it's of course feasible to use manually created .md files until a (parseable) standard for embedding that info into help patches has emerged and been adopted.

[porres]

I think "float/symbol" is fine. Fixed the rest in ELSE/Cyclone

[umlaeute]

i think float/symbol may be fine from the POV of succinct documentation.
but from the POV of automatic tooltips (or more general: machine parseable documentation), I think keeping them separate should probably be preferred, like:

  - type: float
    description: to replace format specifiers.
  - type: symbol
    description: to replace format specifiers.
  - type: set <string>
    description: message replaces format.

(as a sidenote, i think that the half-sentence "to replace specifiers" could do with some improvements anyhow)

the raison d'être of the front-matter in the .md files is machine parseable information (from which human readable documentation is generated).

[porres]

I see, I could change that then

[porres]

just changed it in the help files and it looks better now

[porres]

so, any more 'doubled' things left besides float/symbol or float/list?

[porres]

So, I opened this discussion but couldn't get to it because of all the overload.

It was one of my main desires, to add the full documentation of Pd also up online, specially the "reference". The thing is that I am not motivated really anymore and I don't see anyone else up for it as well. Truth is that working on help files alone is a humongous work load on its own and over the years this has proven to be very time consuming.

The tendency is to stabilize things over the years and I guess we can finally say that the help files have correct and stable reference info, but I still have in the back of my mind a to do task to revise it once more.

Thing is that working on both help files and md feels kind of a nightmare, I couldn't do it myself for ELSE, @tomara-x and @vasilymilovidov did all .md files for ELSE like a year and a half ago and I was lazy to keep up with it and now I guess we'd have to revise everything from scratch and it's like 550 objects for now... I'm not up for it...

Vanilla should be easier and much more stable and something to consider now, and I haven't fully given up on it and will keep this idea in the back of my head and maybe revisit it and reopen this discussion or something, but for now I'm closing it.

It's actually impossible to forget as the .md files are on the repository... and I guess anyone else that replied here could work on it if desired, let me know...