Add html reference to manual (as an online resource option as well)

[porres]

I'll do this first => #6

later we can think of an online documentation reference

old discussion in #10

---

Idea is to have all objects' basic description of functionality (example [float]: - store a float), then document messages to/from in/outles and creation arguments.

A first draft is here for the first 4 objects https://lucarda.github.io/pandoc-and-reference/

Pd-ceammc also has something similar, here for reference: https://ceammc.github.io/pd-help/help-en/

It could be part of Pd's manual as an appendix. This means it would live online in Miller's site and also be shipped with pd.

There could also be a dedicated link to it from within Pd (as in a link from Help menu).

[Lucarda]

@porres see https://pd.iem.sh/list-of-objects/

only the first 4 objects opens more description.
There might be a nicer layout in the .md of each description.

[porres]

Now that 0.52 is out and I made tons of changes/revisions it's time to start adding reference subpatches in the help files.

@Lucarda I don't really like this idea to index inlets/outlers from '0'. I'm using a standard.

here's my template so far

anyway, when done, we can copy these to an html

[porres]

the branch I'm adding reference subpatches -> https://github.com/porres/pure-data/tree/add-reference

[porres]

I'm done adding references in pure-data/pure-data#1517

It's time to work on the html files I guess, can I count on your help @Lucarda ?

[porres]

It's time to work on the html files I guess, can I count on your help @Lucarda ?

this would require us to revise my initial work, which must still include mistakes and typos...

[umlaeute]

related: pure-data/pure-data#1517 (comment)

[abreubacelar]

so maybe we could do the inverse, extract all the info porres put on the patches and create meta files and after create the mechanism that recreate the patches and html files from the meta files?

so before anything... where is some description of how a meta file should be written? or we need to first agree on the format ourselves?

[Lucarda]

@porres

can I count on your help @Lucarda ?

Yes

@abreubacelar

so before anything... where is some description of how a meta file should be written? or we need to first agree on the format ourselves?

In pd-extended meta files where patches only containing pd comments. something like:

...
#N canvas 910 105 580 571 reference 0;
#X text 136 432 signal - signal output to sound card;
#X text 123 510 1) list - set output channels (default: 1 2);
#X text 132 160 signal - signal input from sound card;
...

This way we can easily parse the text.
What is not yet clear to me is if this is possible in sub-patches (is there a way to know when a sub-patch ended?). May be there has to be one abstraction per reference?

May be @umlaeute already has another idea?

[porres]

how would this work in help files that have the same help file? like [table], "garray", graphs and subpatches?

Or objects like text/array/file that have multiple functions?

For these cases I had different [pd reference] subpatches for each.

Also, some [pd reference] subpatches include multiple objects at once, like in the help file of fft~ and related objects...

I think that once this is done, it's not like we'll keep changing what the funcionalities are... and when something changes, we need to update the help file anyway... I'm usually the one doing that and I don't mind manually adding the same changes to the html files eventually...

[Lucarda]

@porres I would like to do some testing on how feasible is to auto-extract-and-deploy info from .pd files to end up, via HUGO, in the online resource (the now hypothetical https://pd.iem.sh).

To cut it short these are the needs for my proposed plan:

• (optional) a new branch on top of what you already had done.

• restrict the reference patches to only use comments.

• make a patch that extracts the info to a plain text file.

• do the stuff so that HUGO gets those text files into the HTML site.

We should start slowly with a couple of examples to evaluate all steps and the results.

We should give-up all the "visually niceness" both in .pd and .html files.

We should restructure the reference patches to fit or satisfy our new imposed needs.

We should do these tests together (you, me, @umlaeute , (others welcome)) so that we distribute our time, efforts and knowledge.

---

I would like to have green lights from you and @umlaeute .

If I don't get the green lights someone will have to do a big and slow copy/paste to get an html reference (also hard to maintain later).

[porres]

We should give-up all the "visually niceness" both in .pd and .html files.

Doesn't seem worth it.

someone will have to do a big and slow copy/paste to get an html reference

I can do it. Just help me out with it until I get the hang of it.

(also hard to maintain later)

It's not like messages/methods change all of the time. I really think this is a one shot task that will require minimal headaches to keep it up. Anyway, I'm up for it...

[Lucarda]

I really think this is a one shot task that will require minimal headaches to keep it up.

I agree mostly.

We should give-up all the "visually niceness" both in .pd and .html files.

Doesn't seem worth it.

At least in the html files there will be few give-ups (they are already limited).

I can do it. Just help me out with it until I get the hang of it.

Yeah I know you can do it, its very straight forward.

Just install HUGO

https://gohugo.io/getting-started/quick-start/#step-1-install-hugo

then clone https://git.iem.at/pd/pd.iem.sh (you can sign-in with your github account)

on a terminal placed on the cloned folder do hugo server

Create a branch and start filling the .md files in content/objects

you will have live-preview in your browser whenever you hit save on the .md file(s)

that's a start.

---

I had sketched html-ref-hugo-wip.zip to parse "META" or "reference" segment in help patches.

I'll investigate further on this challenge.

[Lucarda]

ping @porres

I'm ready to start a "big and slow copy/paste".

Did you already started?

[porres]

not ready :/ I also couldn't clone the repository either yet...

[Lucarda]

Is it OK if I start?

My plan is to do all the bulk transfer. Later we do more fine tuning as needed.

[porres]

go ahead :)

[Lucarda]

@porres check https://pd.iem.sh/objects/. All objects in "General" were filled.

[umlaeute]

afaict, the problem with the certificates is, that cmdline git does not use the (root) certificates from the keychain manager but instead those from /etc/openssl/cert.pem.

(if you can access https://git.iem.at/ with your browser, this means that that the keychain manager can already handle the newer certificates; i haven't checked with the github app, but presumably this just uses cmdline git under the hood, so that's why the keychain manager certificates don't work)

a simple fix (confirmed to work on Catalina) to replace the /etc/ssl/cert.pem with the one obtained from https://curl.se/ca/cacert.pem

on the cmdline this looks like:

sudo cp /etc/ssl/cert.pem /etc/ssl/cert.pem.original
sudo curl -k https://curl.se/ca/cacert.pem -o /etc/ssl/cert.pem

alternatively (e.g. if you do not fully trust the CA certificate from curl; or because you have added additional certificates to your keychain manager, that you do not want to lose), this might work as well ( ⚠️ but I'm unsure about the full consequences; it seems that security find-certificate only exports 4 (four) certificates, whereas the /etc/ssl/cert.pem originally holds about 132, and the one from curl.se holds about 137; so things might not entirely work as expected if you do that ⚠️ )

sudo cp /etc/ssl/cert.pem /etc/ssl/cert.pem.original.1
security find-certificate -a -p > sudo tee /etc/ssl/cert.pem

finally this is of course only an issue if you use https. A much saner, safer and and more efficient way is to use ssh for cloning (which @porres accidentally tried in #46 (comment)).
The trick to make it work is by creating a local ssh-key, and upload the public key to your user profile at https://git.iem.at/-/profile/keys)

[porres]

yay, thanks for the github mirror

[umlaeute]

guys: it would be great if could move chat-like conversations that have nothing to do with the actual issue (just for reference, it is "Add html reference to manual (as an online resource option as well)") to "some other place".
e.g. a dedicated ticket (e.g. on https://git.iem.at/pd/pd.iem.sh/-/issues) or a real chat on IRC/telegram/discord/...

[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.

[porres]

it would be great if could move chat-like conversations (...) to "some other place".

I'm also annoyed about this issue being a chat channel, so here we go, we can keep it at ---> #141