Improve manual 2 section on editing patches (intelligent patching) and more

[porres]

This is a reboot of https://github.com/pure-data/pddp/issues/92

Doing the below list stuff here https://github.com/pure-data/pure-data/compare/master...porres:pure-data:manual-chapter2-revsion

Document "intelligent patching"

source: https://vimeo.com/273707442 https://vimeo.com/279631360 * https://vimeo.com/340437816

• [x] Document 'tab' navigation (objects, connections, outlets and inlets!)

• [x] Document autopatching

• [x] duplicate connections with cmd+d

• [x] shift

  • [x] swap connections: for a selected a connection, click and shift on another connection to swap them.
  • [x] If objects are unselected, click instead of releasing to keep making connections.
  • [x] connect one to many
  • [x] connect many to one
  • [x] for 2 selected objects, it connects all inlets/outlets
  • [x] connect the same outlet of selected objects into many inlets of a single object that is also selected

• [x] cmd+k

  • [x] select 2 objects connect them.
  • [x] Repeat to connect more outlets to inlets
  • [x] For signal objects, repeated to fan out an outlet to more inlets
  • [x] select object and connection or 3 objects to insert
  • [x] select 3 objects to bypass (this and above can be non leftmost connection).

• [x] documenting 'paste + replace'

• [x] Document triggerize

  • [x] insert a trigger when an output is connected to may inlets of one or more objects
  • [x] insert a dummy object and type on it to replace for another. Select connection and do 'comd+t'
  • [x] insert a dummy audio object (nop~) in a signal connection (mention it doesn't have to be leftmost here and above)

• [x] Include screenshots of "Intelligent patching

  General Stuff

• [x] Document more details from the main Pd window, mention turning DSP on and off and 'clear console'

• [x] expand 2.1.4. patches and files to show how to create, set font size and close a patch with shortcuts from th 'file' menu

• [x] Document 'esc' to cancel selection

• [x] improve copy/paste/duplicate/cut section

• [x] Document moving objrets with arrows

• [x] Document 'tyding up'

• [x] Include Of mentioned Menus (File, Edit, Put and Media)

• [x] resolve differences in macOS resp. Linux/Win on 2.1.1.

[porres]

maybe a new 2.3 entry on 'intelligent patching' makes sense? We can then divide into categories (autopatching, shift, control+k) and we keep 2.6 for the most basic stuff

Control-q "quits" Pd, but asks you to confirm the quit. To quit without having to confirm, use command-shift-Q. --> Not true in Macs

Put this somewhere else, maybe after 2.1.1, with a Pd Menu screenshot.

add File Menu screenshot in 2.1.4. patches and files

[ben-wes]

maybe a new 2.3 entry on 'intelligent patching' makes sense? We can then divide into categories (autopatching, shift, control+k) and we keep 2.6 for the most basic stuff

sounds good to me!

Control-q "quits" Pd, but asks you to confirm the quit. To quit without having to confirm, use command-shift-Q. --> Not true in Macs

really? it is true for me on sonoma here for sure. i never use it though - and it also triggers the "quit all applications and log out" dialog of macOS after quitting Pd.

[ben-wes]

@porres : let me know how or if i can contribute here from here still - since i'm a bit lost now after the discussions and not sure if i should continue editing the initial document?

[porres]

really?

really, but on 10.14.6, so maybe this is too old...

let me know how or if i can contribute here from here still - since i'm a bit lost now after the discussions and not sure if i should continue editing the initial document?

@ben-wes, it doesn't make sense to edit that document anymore. I am using it and the vimeo videos to make a list of things with checkboxes here, so I can add it all to the manual. i hope you can contribute by checking if the list is missing something and also by proof reading and giving feedback on things I'm writting.

[Lucarda]

porres-data™ has started his usual ...

@porres how about coping all folder 1.manual into somewhere on branch https://github.com/pure-data/pddp/tree/wip-0.55

so we have access to only the manual. You (with us helping) go through all the changes and include the new pics.

When it's done you copy all the contents of the folder into your documentation branch: yes a big overwrite, all the changes are there so you:

git add -A (add all the new pics) git commit -am "you name it"

we can help you better this way, I think.

Then we delete wip-0.55 branch

What do you say?

[porres]

how harder is it to collaborate to a branch in my repo?

I started a new branch by the way and made a big revision up to 2.3 https://github.com/pure-data/pure-data/compare/master...porres:pure-data:manual-chapter2-revsion

next, rename 2.3 to "inteligent" pathcing and move things up (2.3 becomes 2.4, etc...)

[Lucarda]

I would like to use <code> for referring to a key or key combination.

<code>ctrl/cmd + /</code>

instead of <bold>

<b>ctrl/cmd + /</b>

not only I liked better but it will be of much use if we ever convert the .htm to .md (we might need to do this in the future)

also I don't like much ctrl/cmd we better use one or the other.

I can handle working on your repo. Do I go ahead with my changes?

EDIT: there is a special <kbd> html tag for keys but is not of much use without some nice CSS(this can be done) but not sure how it will be interpreted when converting .html to .md

[porres]

Do I go ahead with my changes?

yes

[Lucarda]

done via https://github.com/porres/pure-data/pull/35

[porres]

also I don't like much ctrl/cmd we better use one or the other.

even though I am an apple guy, feels 'ctrl' should be preffered... mac people know that 'control' is 'command'

[porres]

new idea, I think 2.1.4. patches and files should expand and show how to create, set font size and close a patch whith shortcuts from th 'file' menu

[porres]

even though I am an apple guy, feels 'ctrl' should be preffered... mac people know that 'control' is 'command'

nonetheless we also have 'control' key in mac... now I feel that having both makes sense

[porres]

for now I'm leaving 'cmd'...

[porres]

ok @Lucarda , made more revisions, can you take care of adding pictures/screenshots of menus?

"Post screenshots of Menus. the File, Edit, Put and Media Menus are mentioned in chapter 2, so let's add them where they are mentioned. Edit Menu's screenshot could be right at the beggining of 2.2. editing Pd patches and 'Put Menu' at creating boxes subsection."

[porres]

added 2.3 on 'advanced editing' to document checkboxes under 'intelligent patching'

[porres]

Ok, just documented tab navigation, autopatch, duplicate connections and 'shift'…

only 'cmd + k', triggerize and paste replace to go... will work some more today, but this is something I could do and finish in a day, so no need to wait post .55 :) what I want help with is images... I left (INCLUDE PIC) remarks...

[porres]

Ok, just documented tab navigation, autopatch, duplicate connections and 'shift'…

https://github.com/porres/pure-data/commit/8774e0f3fd658a96e06e4a60d41bf0435b7415c1

[Lucarda]

I'm leaving home for the weekend but i'm carring a machine. Will try to get the pics (i have a linux usb drive with debian10 lxqt that i used for the actual pics).

[porres]

great, cmd+k is done, only triggerize and paste replace to go...

If I have nothing to do, I'll finish this over the weekend :)

[porres]

here's a picture model for swaping connections

[porres]

ok, only triggerize left to go... I'm calling it a day... but it's all almost done...

here's a patch I used to guide me and the above screenshot is from it... no paste replace and triggerize here yet

chapter2.pd.zip

[porres]

ok, there's a thing IOhanness does at the end of the last video, and it's not possible on a mac...

• tab cycling through target inlets while dragging (only possible on Linux and Windows since it relies on manipulating the mouse position)

I can't test it, so how does it work?

@Lucarda , @ben-wes ?

[Lucarda]

(only possible on Linux and Windows since it relies on manipulating the mouse position)

strange. don't understand what's the mac restriction on "manipulating the mouse position"

it works for me as in the video on Windows.

PS: My debian10 ltqx is very old and i got in troubles. Tomorrow i'll try to get a modern version and compile Pd to get the pics.

[porres]

it works for me as in the video on Windows.

I dont understand how it works, can you explain it? It is the last thing for me to document now.... just included triggerize

I also don't know what is the restriction in mac

[porres]

there is a shortcut in Pd that requires us to use the 'control' key in mac (not the 'commnd' one). What is the corresponding key on PCs?

[porres]

where is 'edit preferences' on PCs?

[Lucarda]

I dont understand how it works, can you explain it?

[unpack 0 0 0]

[pack 0 0 0]

make a connection from outlet 1 to inlet 1 but don't release the click when you are over inlet 1. While holding the mouse button pressed on 1st inlet. press the tab key. it will connect 1st outlet to 2nd inlet. pres tab ... . connection is done when you release the mouse button.

[Lucarda]

where is 'edit preferences' on PCs?

[Lucarda]

there is a shortcut in Pd that requires us to use the 'control' key in mac (not the 'commnd' one).

which shortcut?

What is the corresponding key on PCs?

don't know.

[porres]

make a connection from outlet 1 to inlet 1 but don't release the click when you are over inlet 1. While holding the mouse button pressed on 1st inlet. press the tab key. it will connect 1st outlet to 2nd inlet. pres tab ... . connection is done when you release the mouse button.

funny this can't be done on macs, how you can't "manipulate the mouse position"

which shortcut?

show previous/next tab

[porres]

funny that in mac you dont have those things under "File". I wonder why...

[porres]

Anyway, I'm done, just add some pics and we're good to go, you both can proof read my changes, look for typos, see if the text makes sense and if I missed anything from "intelligent patching". I will do, of course, more revisions

[porres]

let's modernize some of the pictures... fig11.1 needs a new screenshot, as it has a whole new look and design

cyclone search in deken shows 0.3, it is in 0.8.1 now, also, deken looks different with the new version, let's show it

[porres]

fig4.1 should also be updated

[porres]

also, I don't like fig1.1 and how it shows that priority error, that shouldn't be there, right?

[Lucarda]

@porres there's https://github.com/porres/pure-data/pull/36 with many updates

this PR covers

• updating the index with the new sections.
• updating internal links.
• breaking long lines in the code.
• update many of existing images.

does not covers

• new images.

[Lucarda]

also: @porres i liked very much how you integrated all the data into the manual. I'm having trouble with generating the new images, may be you already have a proper visualization already in mind?.

can you (or @ben-wes) do the new pics?

if there's trouble integrating them you can send me those as patches so i screen them?

whatever it comes up i think the naming scheme could be changed so as to avoid having fig.x.x.png. (but may be i'm wrong).

[ben-wes]

can you (or @ben-wes) do the new pics?

i could check the current state of this and create some snapshots later today (CET). @porres let me know if this sounds good to you or if you plan to do that yourself.

[porres]

sounds great

[ben-wes]

if there's trouble integrating them you can send me those as patches so i screen them?

i'd do both: create pictures and add a zip of corresponding patches here (if anyone cares about consistent appearance - since my macos screenshots will look different from win/linux ... although i'd at least check that the resolution matches)

whatever it comes up i think the naming scheme could be changed so as to avoid having fig.x.x.png. (but may be i'm wrong).

what scheme do you have in mind? when seeing the current state, it's a bit confusing to me, too, since with the increasing ids, adding pictures anywhere inbetween doesn't work well.

how about renaming them to fig<chapter>.<slug>.png where the slug would actually describe them (in most cases derived from the corresponding headline)? i could do that for all pictures.

and i'd also replace all jpgs with pngs since the former don't really make sense for these kinds of screenshots.

[Lucarda]

if you are not going to do all the html stuff simply supply the new pics with the new names scheme.

how about renaming them to fig<chapter>.<slug>.png where the slug would actually describe them (in most cases derived from the corresponding headline)?

• ok, use fig<chapter>.<slug>.png for the new files only. (it could be fig-ch2-<the-slug>.png)
  • (no "white space" in file name (you-know-what-i-mean))

i could do that for all pictures.

• ok

and i'd also replace all jpgs with pngs since the former don't really make sense for these kinds of screenshots.

• ok (if possible just convert the existing files (i think).

[ben-wes]

ok, use [...] for the new files only.

ok, i'd proceed with fig-ch<chapter-number>-<the-slug>.png ... so no more period in the name except for the file extension?

no "white space" in filename (you-know-what-i-mean)

yep! that's what i was mainly thinking of when referring to "slugs". :)

if possible just convert the existing files

i wouldn't suggest that - since then the lossless png compression will persist the jpg artifacts (which will create bigger pngs without any advantage). let's see ... i'd do that last anyway - but if so, we should create new images for the current jpgs, i think.

[Lucarda]

i wouldn't suggest that - since then the lossless png compression will persist the jpg artifacts (which will create bigger pngs without any advantage). let's see ... i'd do that last anyway - but if so, we should create new images for the current jpgs, i think.

ok. go ahead with new ones. (thanks for pointing it out, i know nothing of pics and the jpgs were in the original manual, so i just use the same file extension)

[ben-wes]

ok. go ahead with new ones.

alright, thanks for the clarifications! i'll start with this in ~5h then!

one more minor question came up when browsing through the current version: for me, there was one case where the shortcut text had a line break. can we use   for the spaces in shortcuts or will that further complicate the conversion back to md?

[ben-wes]

(ah, i think markdown supports   anyway      <-- like here)

[Lucarda]

i could not find the line break but anyhow yes replace it (it shouldn't be there). :)

[ben-wes]

sorry - that a misunderstanding since my words weren't very precise: there's no actual newline character or so. the line is just breaking like it should :) - but i would prevent the shortcuts to break with the  s

[Lucarda]

that could be

<P> <code>Cmd  + Q</code> "quits" Pd, but asks you to confirm the quit.</br>  
To quit without having to confirm, use <code>Cmd + shift + Q</code>.

[ben-wes]

that could be

ok, sure - that's a good option to avoid it in this case! anyway, i'd just use <code>Cmd&nbsp;+&nbsp;anykey</code> for shortcuts, ok?

and then please choose the object size / resolution for the screenshots ... :) (i assume we use the default of 12pt regular?)

[Lucarda]

<code>Cmd&nbsp;+&nbsp;anykey</code>

i think its useless inside a <code> tag as it indicates no prossessing just text (had not checked it out)

12pt regular?

12 or 16 its ok.