Revise chapter 2, add "intelligent patching" and more

[porres]

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

Changes are being made at https://github.com/pure-data/pure-data/compare/master...porres:pure-data:manual-chapter2-revsion and changes include the checklist below and other revisions.

Document "intelligent patching"

Document many things under a new chapter subsection. Many of these features are described in the source: https://vimeo.com/273707442 https://vimeo.com/279631360 * https://vimeo.com/340437816

• [x] 'Tab' navigation

  • [x] objects
  • [x] connections
  • [x] outlets
  • [x] inlets

• [x] Autopatching

  • [x] items from the put menu with shortcuts
  • [x] add subpatches with inlets

• [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] 'paste + replace'

  • [x] replace boxes of the same type for another box that does not need to be of the same type
  • [x] only boxes of the same type are replaced

• [x] 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] insert leftmost outlet
  • [x] remove unused outlets
  • [x] create outlets for extra connections

• [x] Include screenshots figures for this whole section and for every case above

  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 the 'file' menu

• [x] highlight shortcuts

• [x] document 'esc' to cancel selection

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

• [x] document moving objects with arrows

• [x] document 'tidying up'

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

• [x] replace animated gif for deken in chapter 4 for a static image

• [x] mention that on Pd64 numbers are kept 64-bit floating point

• [x] various cleans to the html code

• [x] move images and resources to new folders

• [x] reorganize and renumber images

• [x] modernize 'data structures' section (update patch to the current version with [clone])

[Lucarda]

here we can mention that on Pd64 numbers are kept 64-bit floating point

https://github.com/porres/pure-data/blob/fcf397c39078f05d2e957b39684ccbb20d13cb01/doc/1.manual/x2.htm#L725C1-L733C36

[porres]

So, I have a new (INCLUDE PIC) request :) please check it, what I have in mind

[porres]

are you people not finding any issues with the text?

[ben-wes]

are you people not finding any issues with the text?

I'll probably find stuff. didn't get to properly read yet once more since I had a working day til now and will be afk for a bit. I remember that there was still at least one mention of "accelerator" instead of "shortcut" somewhere. but I'll check in a few hours (and add the pic)

[Lucarda]

i used this patch to tell that numbers are ok

[porres]

is this good? Can you add some space below the table now?

[Lucarda]

Can you add some space below the table now?

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

[porres]

OK, all done... I'd like an 'ok' for text revisions, that new pic, and I'm merging :)

[ben-wes]

the pictures in 2.1.2. Object boxes and 2.2.2. Creating boxes will be redundant then, @porres (the put menu in both cases)?

[porres]

what do you mean? I just wanted a pic to show the 'X' cursor and the connection seldcted

[porres]

oh, forget that first one and remove it :)

[porres]

@ben-wes just make the connection selected in blue please

[porres]

I removed it, check it out

[ben-wes]

created PR https://github.com/porres/pure-data/pull/52 ... still didn't read everything - unfortunately also won't manage today. there are 3 lines mentioning "object proper" - and i admit that i don't know what this is supposed to mean.

[ben-wes]

@Lucarda : i changed </br> to just <br>. imho, the former is not proper html since a closing tag alone there doesn't make sense (<br/> would be valid, but not necessary). when i check with the w3 validator, i now only get complaints about the header line:

<meta http-equiv="Content-Type" content="text/html">

... i assume we could just omit that one. but it's been there forever - so maybe no need to change it now.

[Lucarda]

@ben-wes i always forget which is the valid "line break" :)

about <meta http-equiv="Content-Type" content="text/html"> i'll check it tomorrow but not a problem really

[ben-wes]

@ben-wes i always forget which is the valid "line break" :)

... that sounds familiar, haha - same here. :)

@porres : i added another commit to my PR rephrasing the "object proper" stuff. please check if they sound good to you that way: https://github.com/porres/pure-data/pull/52/commits/43ed39f62289faf20883af5133f31868ad107cc7

[ben-wes]

and to both of you, @porres @Lucarda : i admit that i only now learnt about "american punctuation" vs. "logical punctuation". i did some corrections here in the past where i moved commas or period outside of quotation marks - not knowing that this is valid in american english. to me (and also from a programming syntax perspective), this is totally weird and i prefer the logical version. anyway: sorry for those uninformed changes!

[porres]

This always seemed weird to me and it always felt like an error and something that miller came up with, hahahaha... so it is actually wrong for us to have "logical punctuation"? In a world perspective this looks weirds

[porres]

still didn't read everything

tell me when you're done

[ben-wes]

so it is actually wrong for us to have "logical punctuation"?

the whole topic is quite a rabbit hole and i refuse to go deeper, haha. short answer is: no, it's valid and even required by the style guides of some major American newspapers. and also: "American punctuation" doesn't even seem to be the correct term.

[Lucarda]

@porres there is https://github.com/porres/pure-data/pull/53

• move images and resources to new folders

• various cleans to the html code

@ben-wes this <meta http-equiv="Content-Type" content="text/html"> was updated to

<meta http-equiv="content-type" content="text/html; charset=UTF-8"> and passes the validation

[ben-wes]

i added one PR from my side as well (rebased to @Lucarda's latest changes): https://github.com/porres/pure-data/pull/54

• rephrased some paragraphs (still didn't read through all)
• consistent lowercase for "menu" (that was mixed before - i wouldn't object "Menu" neither, but it should be consistent)
• line lengths are a bit more equal now (makes editing side by side here easier for now and in the future)

[ben-wes]

concerning 2.10.4. Limitations: Miller plans to make data structures more convenient to work with iirc - not sure what the plans are, but the changes will possibly affect this paragraph?

[ben-wes]

i did proofread everything now except for 2.10 (data structures) and created a new PR with quite a few corrections: https://github.com/porres/pure-data/pull/55

2.7 seems to be a bit redundant in some parts - but at the same time is more detailed. altogether, i really like chapter 2 in this version now! i actually learnt a few new things while reading it now. :)

EDIT: if you want to review these changes, this view here is probably more convenient than the default: https://github.com/porres/pure-data/pull/55/files?diff=split&w=1

EDIT2: i'm not planning to proofread the data structure part - so from my side, i currently consider this done!

[Lucarda]

I could not do any reading as I'm working on other stuff. It should be ok I think :) (and it can always be edited later :) )

[porres]

I'm making a deep revision once more and calling it done. I guess you changed "boxes" to "objects" in many cases @ben-wes , which is making me work hard again :) to think when we should have the more general term "box" that includes GUIs, number boxes, messages, etc rather than "object", which is a specific type of box. I guess it's come to a point where we can just revise for typos and mistakes, and suggest other conceptual changes with discussion before changing it.

[porres]

ok, enough is enough, I'm merging, and haven't made a full revision cause I cannot take it anymore, hahaha, thanks a lot!

[porres]

hey, github desktop offered me to "squash and merge" :)

[Lucarda]

:)

[porres]

well, I guess it'd be best to not squash, cause I think I would finally pass dan in the number of commits with this, hahahaha

[Lucarda]

:)

good work anyway :)

[ben-wes]

I guess you changed "boxes" to "objects" in many cases @ben-wes

@porres : i see the semantical difference and certainly didn't intend to do so, no. maybe it slipped in in some cases, where i consulted deepl or chatgpt for easier ways to put a sentence. but if i check my link above, i don't really see these changes!? (and i also didn't copy/paste anything without reading every single word.)

just open https://github.com/porres/pure-data/pull/55/files?diff=split&w=1 and search for box/object to highlight these. hmm ... i wonder which changes you mean now?

what i see is that you went back to the non-logical punctuation (like "this," for example). maybe i misinterpreted your last comment on that above - but i thought you found that weird, too? :)

and i see a few typos when quickly scanning the diff:

• "devicesin": https://github.com/pure-data/pure-data/pull/2233/commits/432a6463b600c266665832b505f81ef23540cc99#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R69
• "erros": https://github.com/pure-data/pure-data/pull/2233/commits/432a6463b600c266665832b505f81ef23540cc99#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R84
• "selectoin": https://github.com/pure-data/pure-data/pull/2233/commits/432a6463b600c266665832b505f81ef23540cc99#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R305
• "momde": https://github.com/pure-data/pure-data/pull/2233/commits/432a6463b600c266665832b505f81ef23540cc99#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R432

[ben-wes]

but anyway ... happy when we're done with this. thank you both! i won't add another PR at this point. :)

[ben-wes]

ah, and this is not part of your changes, @porres - but here it should probably link to x4.htm:

https://github.com/pure-data/pure-data/commit/432a6463b600c266665832b505f81ef23540cc99#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R50

... and i guess the "Externals" chapter should be titled with an uppercase "E"

[porres]

You can send a PR please with the typo fixes, could be directly to documentation branch now

[ben-wes]

EDIT: solved.

hmm ... i can't seem to make a simple PR with that last commit against pure-data/documentation could you support maybe? - this is the commit: https://github.com/ben-wes/pure-data/commit/936e0b04a00f462312285f300f25376ce3643551

[ben-wes]

ok, managed now. should have known that after the squash it's easier with a new branch: https://github.com/pure-data/pure-data/pull/2234

[porres]

thanks, hoping miller includes this right away, I should stop and focus more on other things now, but would like to get back to this for more manual revisions for the update.

i thought you found that weird, too? :)

it is, but that's the original format and not all were changed, so I reverted back. I'm still not sure it is ok to use the 'logical' format, what do you say? We need to do it in all help files and chapters...

as for when things changed, I don't know, and I don't know how to look it up... just know I needed to redo it, but don't worry, it's fine, it's already done and it happens. Thanks for reviewing it. I just have to stop as I know I'm just gonna check for typos and end up rewriting A LOT, making lots of surgery and generate more typos.

I thought we could have yet a new image showing an uncreated object box in "dashed form" (is this phrasing correct? I just added that info into the manual last time). What do you think?

[ben-wes]

I'm still not sure it is ok to use the 'logical' format, what do you say? We need to do it in all help files and chapters...

i'd be glad to change it everywhere. but maybe not for this revision now. iirc, the changes in x2.htm were quite complete, since there are exceptions (when a whole sentence is quoted for example).

here's wikipedia's take on this, which i find pretty ... logical. :)

Using logical quotation in articles in American English is not "bad grammar", but supported by major journals, and increasing in use in the general populace. Typesetters' quotation is a loose, ambiguous style common in fiction and journalism and is not suited to encyclopedic writing. Wikipedia uses logical quotation – do not add punctuation that is not part of the original quotation – by consensus, because it is accurate. https://en.wikipedia.org/wiki/Wikipedia:Logical_quotation_on_Wikipedia

as for when things changed, I don't know, and I don't know how to look it up... just know I needed to redo it, but don't worry, it's fine, it's already done and it happens.

i was curious now and am certainly nit-picking a bit. but to give you some examples of the object->box corrections you did:

• https://github.com/pure-data/pure-data/commit/432a6463b600c266665832b505f81ef23540cc99?diff=unified&w=1#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R409
  • --> "object" as well in current master: https://github.com/pure-data/pure-data/blob/master/doc/1.manual/x2.htm#L309
• https://github.com/pure-data/pure-data/commit/432a6463b600c266665832b505f81ef23540cc99?diff=unified&w=1#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R83
  • --> "object" as well in current master: https://github.com/pure-data/pure-data/blob/master/doc/1.manual/x2.htm#L90

... but at the same time, i admit that actually some changes slipped in for the worse in my earlier edits - sorry for these and for causing you additional work there! (https://github.com/pure-data/pure-data/commit/432a6463b600c266665832b505f81ef23540cc99?diff=unified&w=1#diff-cf4e3e25e3505e15864d6cba90cf0936ab9a0546b1714b42a8a1ab3de144dab9R271 for example). won't happen again!

I just have to stop as I know I'm just gonna check for typos and end up rewriting A LOT, making lots of surgery and generate more typos.

i know what you mean. same here. :) ... it's ok if we manage to actually still improve things - but should probably stop at some point and switch to other tasks again, haha!

I thought we could have yet a new image showing an uncreated object box in "dashed form" (is this phrasing correct? I just added that info into the manual last time). What do you think?

i updated my branch with these commits here - feel free to check and give feedback (i'd prefer not to create too many PRs against pure-data/documentation): https://github.com/pure-data/pure-data/compare/documentation...ben-wes:pure-data:docs-manual-fix?expand=1

[ben-wes]

@porres : in the "Triggerize" chapter, we're still missing relevant interactions for Ctrl + T action on selected trigger objects imho:

• if all outlets are connected, this adds an additional outlet at 1st position
• if some outlets have multiple connections, all connections will be distributed

• if there are less connections than outlets, the additional outlets will be removed

  what do you think? i use this a lot and i think, we should teach it.

[porres]

I don't even know about this, wanna add it?

[ben-wes]

I don't even know about this, wanna add it?

please check https://github.com/pure-data/pure-data/compare/documentation...ben-wes:pure-data:docs-manual-fix?expand=1

[ben-wes]

@porres : i made one more update and force-pushed. if it looks good to you, feel free to merge it.

and let me know if i should work through the whole manual (all chapters) to correct quotes and brackets for following the logical rules according to the wikipedia statement above. imho, the current form is not appropriate for a manual - but of course, that's also not the most relevant thing to to now.

[porres]

go ahead

[ben-wes]

@Lucarda since you changed the <pre> font-size to 90%: should we do the same for <kbd>? i copied the 80% for kbd from there to have consistent sizes (although consistency here might not be relevant if it looks alright in the text).

[Lucarda]

@Lucarda since you changed the <pre> font-size to 90%: should we do the same for <kbd>?

no. it looks good here on Win and I think i saw it on linux 2 days ago and seems fine. <pre> is independent of <kbd> and vice-versa IIRC. Also I like 80% on <kbd>

[ben-wes]

go ahead

@porres: i have this commit here now for these changes including minor formatting clean-up: https://github.com/pure-data/pure-data/compare/documentation...ben-wes:pure-data:docs-manual-fix?expand=1

... a bit of background:

• periods in brackets or quotes were kept if they included a full sentence (which is according to the "rules" of logical quotation)
• i had these changes also in x5.htm - but it looks like Miller himself used/uses "typesetters' quotation" and it feels wrong to revise this document to me (which is a kind of log and therefore should keep its form imho).

Here's more information on this topic besides the quote in my comment above: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Order_of_punctuation ... as you can see, both approaches are valid and have some prominent followers. i think that for a manual that names lots of things (and especially specific syntax and object names) in quotes, the logical version is way less ambiguous and confusing though.

anyway: no worries if you don't want to merge this!

[porres]

we keep logical then

[ben-wes]

we keep logical then

alright - but just to not confuse the two: we keep "typesetters' quotation" now - not the "logical" one. :)