Document differences with handling newlines between pd-vanilla and plugdata

[anxefaraldo]

Hi again,

Writing compound messages on a single message box (separated by semicolon) does not work as expected: The enter key does not create a newline, but exits the message box editing cursor. A workaround is to use shift+enter, which does create a newline.

I wonder if this behaviour is fully intended, since it deviates from programming in vanilla.

(Intel Mac 2019 with OS13 Ventura)

[timothyschoen]

It was somewhat intentional, since for all other objects enter will close the text editor (this is not a thing in pd, but I think it's a good thing to have). I figured it would be good to be consistent.

But I'm not completely decided on this yet, we can change it.

[dromer]

Shift-enter is different UX from PD vanilla, but otherwise a very common UX in just about every other text entry program (like chat apps).

It is indeed a compromise, but not one that is too confusing for the typical user. If you switch back and forth between regular pd a lot I can imagine certain things can get a bit confusing, but this would not be the only UX that is slightly divergent here.

[anxefaraldo]

I can easily buy this alternative. It is consistent and, as @dromer comments, it makes sense in the more general computer-typing logic.

For me, this particular issue was more of a question about this particular behaviour –as it is now confirmed as intentional– to eventually think of it as a feature rather than as an uncertain property diverging from pd-vanilla, and potentially prone to change in the future (writing this paragraph from a teacher's perspective). I am teaching pd from scratch through plugdata, because it does make a positive difference in many aspects, from layout to daw-bility, etc., so I am really up to incorporating these differences, which can easily be defended as improvements over vanilla's UX.

For me, it would be a matter of documenting these deviations and perhaps adapting vanilla's documentation to plugdata's environment, so that new and old users can find their way through. I could happily help with this endeavour, if that were desirable at some point. I am currently revising the language from basic-to-pro for an academic programme, what can be seen as a good position for revising and/or generating documentation.

[timothyschoen]

I can easily buy this alternative. It is consistent and, as @dromer comments, it makes sense in the more general computer-typing logic.

For me, this particular issue was more of a question about this particular behaviour –as it is now confirmed as intentional– to eventually think of it as a feature rather than as an uncertain property diverging from pd-vanilla, and potentially prone to change in the future (writing this paragraph from a teacher's perspective). I am teaching pd from scratch through plugdata, because it does make a positive difference in many aspects, from layout to daw-bility, etc., so I am really up to incorporating these differences, which can easily be defended as improvements over vanilla's UX.

For me, it would be a matter of documenting these deviations and perhaps adapting vanilla's documentation to plugdata's environment, so that new and old users can find their way through. I could happily help with this endeavour, if that were desirable at some point. I am currently revising the language from basic-to-pro for an academic programme, what can be seen as a good position for revising and/or generating documentation.

I agree, a section on "differences between pd and plugdata" would be a good thing to cover with documentation. Especially for differences like this. It's also good for ourselves remember why we did this in the future, so we don't forget the reason and think it's a bug.

If you're interested in helping out with documentation, @nuoun has created a work-in-progress outline of what needs to be done.

Table of contents

Introduction
    About plugdata
    Documentation guide
    plugdata concepts
        Opensource / platform independent / community driven
        Touchscreen support
        Pure data compatibility
        Included libraries
    Accessibility tips

Getting started

    Downloading plugdata
        Option 1: download page at plugdata.org (recommended)
        Option 2: releases page on github (choose latest official release)

        For linux and macOS: Additional options for packages are listed at the github repository

        iOS version in the app store

        Unstable nightly builds are available at the download page for testing
        old versions available at the releases page

    Differences between running plugdata standalone and as a plugin

    Setting up plugdata
        Configuring audio and MIDI devices
        Testing audio and MIDI IO
        Installing external libraries

Creating your first patch
    Browsing and adding modules and objects
    Creating connections
    Adding effects
    Finding the included examples
    Next steps

Troubleshooting
    Finding console error messages
    Fixing clicks and pops
    Finding help

Learning the plugdata UI
    Overview sidebars, panels and menus
    Three line menu
        Primary / secondary themes and zoom options
        File options
        Workspaces
    Settings window
        Themes
        Paths
        Keyboard shortcuts
        Advanced options
    Popup menu
        Selecting and cut / copy / paste / delete
        Object reference
        Object help
        Properties inspector
    Adjusting tabs
    Palette sidebar
    Panel sidebar
        Console panel
        Documentation panel
        Automation panel
        Search panel
    Display modes
        Edit mode
        Run mode
        Presentation mode
        Plugin mode
        Compiled mode
    Display overlays

Learning programming in plugdata and Pd
    Audio and control signals
    Object properties and arguments
    Subpatches and abstractions
    UI elements
    Graph on Parent
    Hot and cold inlets
    Datastructures: Floats, symbols, lists and bangs
    Arrays, tables and graphs
    Messages
    Blocksizes
    Debugging tips

DAW integration
    Setting up MIDI note data between plugin and various DAWs
        Ableton Live
        Bitwig Studio
        Reaper
        Ardour
        FL Studio
        Studio One
        Logic
    Setting up MIDI CC messages between plugin and various DAWs
    DAW parameter automation example
    Tempo syncing a plugin's internal clock to its host DAW

Standalone MIDI communication and networking
    MIDI communication examples for standalone
    Using Ableton Link
    OSC and other networking options

Compiling Patches (is being worked on already by dromer and thouldcroft)

Resources
    Discord
    FAQ
    Pd manual
    Books
    Videos
    Tutorials
    Sharing patches
    Other resources

Development
    Known issues
    Future android version
    Reporting bugs and requesting new features

Object reference
    GUI elements
    Objects
    Libraries

Glossary of terms

Special thanks

This is great because the first thing we really need for documentation is a way to structure this process. I think your basic-to-pro tutorial could fit into the "Learning programming in plugdata and Pd" chapter. The current structure is not set in stone if your tutorial is different. There is a lot of documentation work to do here, so we are looking for more people who are interested in contributing

We also were looking into incorporating it into the app by using this JUCE markup component. We could also add buttons to open example patches directly from documentation, etc. That would be really nice.

[anxefaraldo]

That's fantastic, Tim, thanks for sharing. I will have a deeper look at the repository and the documentation plan, and see where I can fit. I can definitely contribute materials to the "learning programming..." part, but perhaps there are other parts where I could be helpful too... I'll look for the proper threads to do so...

By the way, yesterday I taught a 6h workshop with the nightly build version... and thanks to all the efforts last week, it all worked MUCH MUCH better!