Commit 4f42d74f authored by Albert Gräf's avatar Albert Gräf
Browse files

Update information about the improved help browser, other small text changes.

parent a5317740
......@@ -8,7 +8,7 @@
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.line-block{white-space: pre-line;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<link rel="stylesheet" href="github-pandoc.css">
......@@ -24,7 +24,7 @@ Johannes Gutenberg University (JGU) Mainz, Germany<br />
December 2017</p>
<p>This document is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>. Other formats: <a href="Purr-Data-Intro.md">Markdown</a> source, <a href="Purr-Data-Intro.pdf">PDF</a><br />
Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">https://agraef.github.io/purr-data-intro/</a></p>
<p><strong>Purr Data</strong> a.k.a. <strong>Pd-l2ork</strong> 2.0 is an improved version of Miller Puckette’s interactive computer music and multimedia software <strong>Pd</strong>. This document provides new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started.</p>
<p><strong>Purr Data</strong> a.k.a. <strong>Pd-l2ork 2</strong> is an improved version of Miller Puckette’s interactive computer music and multimedia software <strong>Pd</strong>. This document provides new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started.</p>
<h2 id="what-is-purr-data">What is Purr Data?</h2>
<p><strong><a href="https://git.purrdata.net/jwilkes/purr-data">Purr Data</a></strong> is the latest (2.x) branch of Ivica Ico Bukvic’s Pd-l2ork. <strong><a href="http://l2ork.music.vt.edu/main/make-your-own-l2ork/software/">Pd-l2ork</a></strong> in turn is a fork of Hans-Christoph Steiner’s <strong><a href="http://puredata.info/downloads/pd-extended">Pd-extended</a></strong>, which has been the longest-running (and arguably the most popular) variant of Miller Puckette’s Pd. <strong><a href="http://puredata.info/">Pd</a></strong> a.k.a. <strong>Pure Data</strong>, the common basis of all these variants, is Miller Puckette’s interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74’s well-known commercial <strong><a href="https://cycling74.com/">Max</a></strong> program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular and very capable applications in the realm of computer music and media art, most notably <strong><a href="http://csound.github.io/">Csound</a></strong> and <strong><a href="http://supercollider.github.io/">SuperCollider</a></strong>. But Max and Pd’s special appeal is that you work in an intuitive graphical “patching” environment which allows you to put together advanced real-time signal processing applications without having to learn a “real” programming language.</p>
<p>Puckette’s version of the program is sometimes jokingly referred to as <strong>“vanilla”</strong> Pd, because it comes without any extras and thus provides the purest taste of Pd, you might say. In keeping with this metaphor, the other Pd variants are often called <strong>flavors</strong>.</p>
......@@ -51,8 +51,8 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<h2 id="where-to-get-it">Where to Get It</h2>
<p>Jonathan Wilkes maintains the Purr Data sources in GitLab at <a href="https://git.purrdata.net/jwilkes/purr-data" class="uri">https://git.purrdata.net/jwilkes/purr-data</a>. There’s also a mirror of this repository at Github which serves as a one-stop shop for the latest source and the available releases, including pre-built packages for Linux, macOS and Windows. You can find this at <a href="https://agraef.github.io/purr-data/" class="uri">https://agraef.github.io/purr-data/</a>. The latest packages for Linux (Debian, Raspbian, Ubuntu), macOS and Windows are available at <a href="https://github.com/agraef/purr-data/releases" class="uri">https://github.com/agraef/purr-data/releases</a>. The Linux packages are in Debian format (.deb files), the Windows package is distributed as an installer executable (.exe file). Normally you can just run the .deb or .exe packages by double-clicking them in your file manager, and walk through the installation procedure. The Mac package is distributed as a disk image (.dmg file); double-clicking the disk image in Finder opens a new Finder window, in which you can drag the application to your Application folder. The Mac and Windows packages should be self-contained, while the .deb packages will pull in a lot of dependencies, which may require some fiddling. (If you’re running Ubuntu or one of its derivatives, and the .deb packages give you trouble, try using the JGU Ubuntu packages instead, see below.)</p>
<p>At JGU we also maintain a collection of Linux packages for Arch Linux (via the <a href="https://aur.archlinux.org/">Arch User Repositories</a> a.k.a. AUR) and recent Ubuntu releases (via <a href="https://launchpad.net/~dr-graef">Launchpad</a>). More information and installation instructions can be found at <a href="https://l2orkaur.bitbucket.io/" class="uri">https://l2orkaur.bitbucket.io/</a> (Arch) and <a href="https://l2orkubuntu.bitbucket.io/" class="uri">https://l2orkubuntu.bitbucket.io/</a> (Ubuntu). Besides Purr Data, these repositories also contain the “classic” Pd-l2ork (Ico Bukvic’s 1.0 version), as well as two additional programming extensions for Pd which enable you to run <a href="http://faust.grame.fr/">Faust</a> and <a href="https://purelang.bitbucket.io/">Pure</a> externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.</p>
<p>Of course, it is also possible to build Purr Data from source. However, because of the large number of included externals, the build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn’t officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.</p>
<p>At JGU we also maintain a collection of Linux packages for Arch Linux (via the <a href="https://aur.archlinux.org/">Arch User Repositories</a> a.k.a. AUR) and recent Ubuntu releases (via <a href="https://launchpad.net/~dr-graef">Launchpad</a>). More information and installation instructions can be found at <a href="https://l2orkaur.bitbucket.io/" class="uri">https://l2orkaur.bitbucket.io/</a> (Arch) and <a href="https://l2orkubuntu.bitbucket.io/" class="uri">https://l2orkubuntu.bitbucket.io/</a> (Ubuntu). Besides Purr Data, these repositories also contain the “classic” Pd-l2ork (at least on older Ubuntu systems where Pd-l2ork 1 still runs), as well as two additional programming extensions for Pd which enable you to run <a href="http://faust.grame.fr/">Faust</a> and <a href="https://agraef.github.io/pure-lang/">Pure</a> externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.</p>
<p>Of course, it is also possible to build Purr Data from source. With the latest additions to the build system, this task has become a lot less daunting than it used to be, and the Purr Data website has some <a href="https://agraef.github.io/purr-data/#building-from-source">instructions</a>. However, because of the large number of included externals, the build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn’t officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.</p>
<h2 id="getting-started">Getting Started</h2>
<p>Once you’ve installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run <code>pd-l2ork</code> from the command line, or look in your desktop environment’s program menu or launcher for the <code>Pd-L2Ork</code> entry and click on that. (If you installed Purr Data from one of the JGU packages, use the <code>purr-data</code> command or the <code>Purr-Data</code> desktop icon instead.)</p>
<p>On macOS and Windows, double-click on the application icon, normally to be found in the Application folder on macOS and on the desktop on Windows. (If you didn’t create a desktop icon during the Windows installation, look for <code>Purr-Data</code> in the start menu.)</p>
......@@ -74,12 +74,12 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
</figure>
<p>One pitfall of the Pd engine is that it does not rescan the devices if you connect new external audio or MIDI gear while Purr Data is already running. Thus you need to relaunch the program to make the new devices show up in the preferences. In the case of MIDI, it is easy to work around this limitation by employing virtual MIDI devices, which ALSA MIDI does by default. On the Mac you’d use the <a href="https://sites.google.com/site/mfalab/mac-stuff/how-to-use-the-iac-driver">IAC</a> devices, on Windows a MIDI loopback driver such as <a href="http://www.tobias-erichsen.de/software/loopmidi.html">loopMIDI</a> for that purpose. You then wire these up to the MIDI hardware using a separate patchbay program. A similar approach is possible with audio loopback software such as <a href="http://www.jackaudio.org/">Jack</a>.</p>
<h3 id="gui-and-startup-options">GUI and Startup Options</h3>
<p>The GUI theme can be selected on the “GUI” tab (see fig. 3, left). The changes will be applied immediately. Purr Data provides various different GUI themes out of the box. Note that the GUI themes are in fact just CSS files in Purr Data’s library directory, so if you’re familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is “save/load zoom level with patch”. Purr Data can zoom any patch window to 16 different levels, and this option, when enabled, allows you to store the current zoom level when a patch is saved, and then later restore the zoom level when the patch gets reloaded.</p>
<p>The GUI theme can be selected on the “GUI” tab (see fig. 3, left). The changes will be applied immediately. Purr Data provides various different GUI themes out of the box. Note that the GUI themes are in fact just CSS files in Purr Data’s library directory, so if you’re familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is “save/load zoom level with patch”. Purr Data can zoom any patch window to 16 different levels, and this option, when enabled, allows you to store the current zoom level when a patch is saved, and then later restore the zoom level when the patch gets reloaded. The remaining options on the GUI tab are related to the help browser, we’ll discuss these in section <a href="#configuring-the-help-browser">Configuring The Help Browser</a> below.</p>
<p>The final tab in the preferences dialog is the “Startup” tab (fig. 3, right), which lets you edit the lists of library paths and startup libraries, as well as the additional options the program is to be invoked with. By default, Purr Data loads most bundled external libraries at startup and adds the corresponding directories to its library search path. If you don’t need all of these, you can remove individual search paths and/or libraries using the “Search Paths” and “Libraries” lists on the Startup tab. Just click on a search path or library and click the <code>Delete</code> button. It is also possible to select an item and add your own search paths and external libraries with the <code>New</code> button, or change an existing entry with the <code>Edit</code> button.</p>
<figure>
<img src="prefs-gui+startup.png" alt="Figure 3: GUI and Startup options." id="fig:fig3" style="width:100.0%" /><figcaption>Figure 3: GUI and Startup options.</figcaption>
</figure>
<p>At the bottom of the Startup tab there is a “Startup Flags” field which lets you specify which additional options the program should be invoked with. This is commonly used to add options like <code>-legacy</code> (which enforces bug compatibility with vanilla Pd) as well as the <code>-path</code> and <code>-lib</code> options which provide an alternative way to add search paths and external libraries. For instance, to add JGU’s Pure and Faust extensions to the startup libraries, the Startup Flags field may contain something like the following: <code>-lib pure -lib faust/pdfaust</code></p>
<p>At the bottom of the Startup tab there is a “startup flags” field which lets you specify which additional options the program should be invoked with. This is commonly used to add options like <code>-legacy</code> (which enforces bug compatibility with vanilla Pd) as well as the <code>-path</code> and <code>-lib</code> options which provide an alternative way to add search paths and external libraries. For instance, to add JGU’s Pure and Faust extensions to the startup libraries, the Startup Flags field may contain something like the following: <code>-lib pure -lib faust/pdfaust</code></p>
<p>Any desired startup options can be set that way, i.e., anything that Pd usually accepts on the command line. However, note that the startup flags require that you relaunch Purr Data for the options to take effect (the same is true if you change the list of startup libraries). Also, while setting paths and libraries via the startup flags is often convenient, there are some downsides to having these options in two different places, see <a href="#sticky-preferences">“Sticky” preferences</a> in the <a href="#tips-and-tricks">Tips and Tricks</a> section below.</p>
<p>As with the other configuration options, remember to press the <code>Ok</code> button in order to have your changes recorded in permanent storage. This will also close the dialog.</p>
<p>Finally, note that if your configuration gets seriously messed up, there are ways to reset Purr Data to its default configuration, see <a href="#resetting-the-preferences">Resetting the preferences</a> in the <a href="#tips-and-tricks">Tips and Tricks</a> section.</p>
......@@ -94,9 +94,19 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<img src="browser.png" alt="Figure 4: Help browser." id="fig:fig4" style="width:100.0%" /><figcaption>Figure 4: Help browser.</figcaption>
</figure>
<p>On the right in fig. 4 you can see how the display changes after you entered a search term like “audio devices” and hit Enter. All related help patches will be shown in the list (with short descriptions of the help patches if available). You can then click on one of the help patches to open it in a canvas window. Clicking on the “x” symbol in the search entry returns you to the home screen.</p>
<p>Note that to keep things simple and not to overwhelm novice users with too much information, the search function only covers the “official” documentation (the doc/ hierarchy). To explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), you must employ the little folder icon to the right of the search entry. This will open a file browser (initially on the doc/ folder) which can then be used to browse <em>all</em> the available help patches. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply point the file browser to that directory and click on one of its subdirectories containing the various abstractions and externals. Double-clicking on a help patch will open the patch in its own window, and then also show the corresponding directory in the help browser, so that additional help patches from the same folder can be accessed without any further ado.</p>
<p>Note that to keep things simple and not to overwhelm novice users with too much information, the search function only covers the “official” documentation (the doc/ hierarchy) by default. There are ways to change the scope of the keyword search in the GUI preferences, see <a href="#configuring-the-help-browser">Configuring The Help Browser</a> below. But in any case it is also possible to explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), by employing the little folder icon to the right of the search entry. This will open a file browser (initially on the doc/ folder) which can then be used to browse <em>all</em> the available help patches. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply navigate to that directory in the file browser and click on one of its subdirectories containing the various abstractions and externals. Double-clicking on a help patch will open the patch in its own window, and then also show the corresponding directory in the help browser, so that additional help patches from the same folder can be accessed without any further ado.</p>
<p>If you already know the name of a subdirectory with interesting help patches, you can also just type its name in the search entry (including the doc/ or extra/ prefix) to have the corresponding folder displayed in the help browser. For instance, typing “extra/mrpeach” and Enter provides a quick way to access the help patches for the mrpeach externals.</p>
<p>Note that in any case, you can always return to the home screen of the help browser by clicking that tiny “x” symbol in the search entry (or by just hitting Enter in the field if it is empty).</p>
<h3 id="configuring-the-help-browser">Configuring The Help Browser</h3>
<p>The GUI tab in the preferences dialog (cf. <a href="#gui-and-startup-options">GUI and Startup Options</a> and fig. 3, left) offers some options to configure the scope of the keyword search. Note that in order to perform keyword searches, the help browser first needs to construct an index of all the help patches and their keywords. This is either done on the fly, when the help browser is first opened during a Purr Data session (this is the default), or when the application is launched (there’s a checkbox which lets you enable this).</p>
<p>Once the browser has been launched, it will always come up quickly on subsequent invocations. But depending on how many patches you are indexing, creating the index on first launch may take a while (anywhere from less than a second to several seconds on modern hardware), so changing these options <em>will</em> have an impact on startup times. If Purr Data seems to launch slowly, being stuck in index generation, and you rarely use the help browser, then you want to make sure that the “prepare the help index at application start” option is unchecked (which is the default). On the other hand, if you’re using the help browser very frequently and it seems to come up very slowly on first launch, you may want to check that option so that index creation is already done after launching the program.</p>
<p>There are two options which let you change the scope of indexed patches:</p>
<ul>
<li><p>If “help browser only searches the doc folder” is checked (which is the default), then keyword searches are confined to the doc/ hierarchy. This is the fastest option and will be sufficient for novice users at least, as it covers all the official documentation that ships with Purr Data. However, if you’re an expert user and frequently use 3rd party externals living in the extra/ hierarchy, then you may want to uncheck this option to have all the remaining subdirectories in the pd-l2ork library directory indexed as well (note that this may slow down indexing considerably).</p></li>
<li><p>The “help browser also searches the help path” option, when checked, lets you tailor the keyword search to the externals you’re working with, so that you won’t be swamped with keyword matches from externals you never use. These externals may be located anywhere you choose, including the extra/ hierarchy (e.g., if they’re distributed with Purr Data), but note that if you’ve already unchecked the “help browser only searches the doc folder” option, then all the externals in extra/ will be searched anyway, so there’s no need to also add subdirectories of extra/ to the help path. In either case, you’ll have to add the directories to be searched to Purr Data’s <em>help path</em> (having them in the library search path is <em>not</em> enough). You do this using Purr Data’s <code>-helppath</code> option which can be added to the “startup flags” field at the bottom of the Startup tab. E.g., on Linux you may want to add something like <code>-helppath ~/pd-l2ork-externals</code> (that directory is often used on Linux for custom and personal external collections).</p></li>
</ul>
<p><strong>Caveat:</strong> Again, be warned that changing these options and then installing external collections with gazillions of patches into either the extra/ hierarchy or on your personal help path may have a very negative impact on startup times, since all these patches will have to be scanned during index creation. Future Purr Data versions will hopefully provide some form of persistence and incremental updates of the search index to mitigate these effects. But for the time being, judicial use of the above options should in most cases give you a sensible setup which does not slow down index creation too much while fulfilling your documentation needs.</p>
<p>Also note that because the search index is created either during program startup or when the help browser is first launched, changing any of the help browser configuration options normally requires a restart of Purr Data to take effect.</p>
<h2 id="pd-l2ork-and-purr-data-goodies">Pd-l2ork and Purr Data Goodies</h2>
<p>Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the <a href="http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf">PdCon 2016 paper</a> for details. The paper also covers the history and motivation of the Pd-l2ork project.</p>
<p>One of Pd-l2ork’s major advancements over vanilla Pd is its <em>infinite undo</em> capability, which makes it easy to revert accidental changes without having to worry about taking snapshots of patches while they’re under development. Many of the other new features are simply GUI and usability improvements which, if done right, quickly become second nature to the user, so that they aren’t even consciously noticed any more, such as the graphical improvements and the ability to resize the IEM GUI elements and “graph on parent” areas using the mouse. A helpful change also worth mentioning here is the improved <em>tidy up</em> option in the Edit menu, which first aligns objects and then spaces them equidistantly.</p>
......
......@@ -9,7 +9,7 @@ This document is licensed under [CC BY-SA 4.0](https://creativecommons.org/licen
Other formats: [Markdown](Purr-Data-Intro.md) source, [PDF](Purr-Data-Intro.pdf)
Permanent link: <https://agraef.github.io/purr-data-intro/>
**Purr Data** a.k.a. **Pd-l2ork** 2.0 is an improved version of Miller Puckette's interactive computer music and multimedia software **Pd**. This document provides new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started.
**Purr Data** a.k.a. **Pd-l2ork 2** is an improved version of Miller Puckette's interactive computer music and multimedia software **Pd**. This document provides new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started.
## What is Purr Data?
......@@ -52,9 +52,9 @@ We also refer to Bukvic's original Pd-l2ork version as Pd-l2ork 1.0 or "classic"
Jonathan Wilkes maintains the Purr Data sources in GitLab at <https://git.purrdata.net/jwilkes/purr-data>. There's also a mirror of this repository at Github which serves as a one-stop shop for the latest source and the available releases, including pre-built packages for Linux, macOS and Windows. You can find this at <https://agraef.github.io/purr-data/>. The latest packages for Linux (Debian, Raspbian, Ubuntu), macOS and Windows are available at <https://github.com/agraef/purr-data/releases>. The Linux packages are in Debian format (.deb files), the Windows package is distributed as an installer executable (.exe file). Normally you can just run the .deb or .exe packages by double-clicking them in your file manager, and walk through the installation procedure. The Mac package is distributed as a disk image (.dmg file); double-clicking the disk image in Finder opens a new Finder window, in which you can drag the application to your Application folder. The Mac and Windows packages should be self-contained, while the .deb packages will pull in a lot of dependencies, which may require some fiddling. (If you're running Ubuntu or one of its derivatives, and the .deb packages give you trouble, try using the JGU Ubuntu packages instead, see below.)
At JGU we also maintain a collection of Linux packages for Arch Linux (via the [Arch User Repositories](https://aur.archlinux.org/) a.k.a. AUR) and recent Ubuntu releases (via [Launchpad](https://launchpad.net/~dr-graef)). More information and installation instructions can be found at <https://l2orkaur.bitbucket.io/> (Arch) and <https://l2orkubuntu.bitbucket.io/> (Ubuntu). Besides Purr Data, these repositories also contain the "classic" Pd-l2ork (Ico Bukvic's 1.0 version), as well as two additional programming extensions for Pd which enable you to run [Faust](http://faust.grame.fr/) and [Pure](https://purelang.bitbucket.io/) externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.
At JGU we also maintain a collection of Linux packages for Arch Linux (via the [Arch User Repositories](https://aur.archlinux.org/) a.k.a. AUR) and recent Ubuntu releases (via [Launchpad](https://launchpad.net/~dr-graef)). More information and installation instructions can be found at <https://l2orkaur.bitbucket.io/> (Arch) and <https://l2orkubuntu.bitbucket.io/> (Ubuntu). Besides Purr Data, these repositories also contain the "classic" Pd-l2ork (at least on older Ubuntu systems where Pd-l2ork 1 still runs), as well as two additional programming extensions for Pd which enable you to run [Faust](http://faust.grame.fr/) and [Pure](https://agraef.github.io/pure-lang/) externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.
Of course, it is also possible to build Purr Data from source. However, because of the large number of included externals, the build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn't officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.
Of course, it is also possible to build Purr Data from source. With the latest additions to the build system, this task has become a lot less daunting than it used to be, and the Purr Data website has some [instructions](https://agraef.github.io/purr-data/#building-from-source). However, because of the large number of included externals, the build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn't officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.
## Getting Started
......@@ -94,13 +94,13 @@ One pitfall of the Pd engine is that it does not rescan the devices if you conne
### GUI and Startup Options
The GUI theme can be selected on the "GUI" tab (see [@fig:fig3], left). The changes will be applied immediately. Purr Data provides various different GUI themes out of the box. Note that the GUI themes are in fact just CSS files in Purr Data's library directory, so if you're familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is "save/load zoom level with patch". Purr Data can zoom any patch window to 16 different levels, and this option, when enabled, allows you to store the current zoom level when a patch is saved, and then later restore the zoom level when the patch gets reloaded.
The GUI theme can be selected on the "GUI" tab (see [@fig:fig3], left). The changes will be applied immediately. Purr Data provides various different GUI themes out of the box. Note that the GUI themes are in fact just CSS files in Purr Data's library directory, so if you're familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is "save/load zoom level with patch". Purr Data can zoom any patch window to 16 different levels, and this option, when enabled, allows you to store the current zoom level when a patch is saved, and then later restore the zoom level when the patch gets reloaded. The remaining options on the GUI tab are related to the help browser, we'll discuss these in section [Configuring The Help Browser] below.
The final tab in the preferences dialog is the "Startup" tab ([@fig:fig3], right), which lets you edit the lists of library paths and startup libraries, as well as the additional options the program is to be invoked with. By default, Purr Data loads most bundled external libraries at startup and adds the corresponding directories to its library search path. If you don't need all of these, you can remove individual search paths and/or libraries using the "Search Paths" and "Libraries" lists on the Startup tab. Just click on a search path or library and click the `Delete` button. It is also possible to select an item and add your own search paths and external libraries with the `New` button, or change an existing entry with the `Edit` button.
![GUI and Startup options.](prefs-gui+startup.png){#fig:fig3 width=100%}
At the bottom of the Startup tab there is a "Startup Flags" field which lets you specify which additional options the program should be invoked with. This is commonly used to add options like `-legacy` (which enforces bug compatibility with vanilla Pd) as well as the `-path` and `-lib` options which provide an alternative way to add search paths and external libraries. For instance, to add JGU's Pure and Faust extensions to the startup libraries, the Startup Flags field may contain something like the following: `-lib pure -lib faust/pdfaust`
At the bottom of the Startup tab there is a "startup flags" field which lets you specify which additional options the program should be invoked with. This is commonly used to add options like `-legacy` (which enforces bug compatibility with vanilla Pd) as well as the `-path` and `-lib` options which provide an alternative way to add search paths and external libraries. For instance, to add JGU's Pure and Faust extensions to the startup libraries, the Startup Flags field may contain something like the following: `-lib pure -lib faust/pdfaust`
Any desired startup options can be set that way, i.e., anything that Pd usually accepts on the command line. However, note that the startup flags require that you relaunch Purr Data for the options to take effect (the same is true if you change the list of startup libraries). Also, while setting paths and libraries via the startup flags is often convenient, there are some downsides to having these options in two different places, see ["Sticky" preferences] in the [Tips and Tricks] section below.
......@@ -126,12 +126,28 @@ Using the Help / Help Browser menu option (shortcut: ctrl + B, or cmd + B on the
On the right in [@fig:fig4] you can see how the display changes after you entered a search term like "audio devices" and hit Enter. All related help patches will be shown in the list (with short descriptions of the help patches if available). You can then click on one of the help patches to open it in a canvas window. Clicking on the "x" symbol in the search entry returns you to the home screen.
Note that to keep things simple and not to overwhelm novice users with too much information, the search function only covers the "official" documentation (the doc/ hierarchy). To explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), you must employ the little folder icon to the right of the search entry. This will open a file browser (initially on the doc/ folder) which can then be used to browse *all* the available help patches. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply point the file browser to that directory and click on one of its subdirectories containing the various abstractions and externals. Double-clicking on a help patch will open the patch in its own window, and then also show the corresponding directory in the help browser, so that additional help patches from the same folder can be accessed without any further ado.
Note that to keep things simple and not to overwhelm novice users with too much information, the search function only covers the "official" documentation (the doc/ hierarchy) by default. There are ways to change the scope of the keyword search in the GUI preferences, see [Configuring The Help Browser] below. But in any case it is also possible to explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), by employing the little folder icon to the right of the search entry. This will open a file browser (initially on the doc/ folder) which can then be used to browse *all* the available help patches. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply navigate to that directory in the file browser and click on one of its subdirectories containing the various abstractions and externals. Double-clicking on a help patch will open the patch in its own window, and then also show the corresponding directory in the help browser, so that additional help patches from the same folder can be accessed without any further ado.
If you already know the name of a subdirectory with interesting help patches, you can also just type its name in the search entry (including the doc/ or extra/ prefix) to have the corresponding folder displayed in the help browser. For instance, typing "extra/mrpeach" and Enter provides a quick way to access the help patches for the mrpeach externals.
Note that in any case, you can always return to the home screen of the help browser by clicking that tiny "x" symbol in the search entry (or by just hitting Enter in the field if it is empty).
### Configuring The Help Browser
The GUI tab in the preferences dialog (cf. [GUI and Startup Options] and [@fig:fig3], left) offers some options to configure the scope of the keyword search. Note that in order to perform keyword searches, the help browser first needs to construct an index of all the help patches and their keywords. This is either done on the fly, when the help browser is first opened during a Purr Data session (this is the default), or when the application is launched (there's a checkbox which lets you enable this).
Once the browser has been launched, it will always come up quickly on subsequent invocations. But depending on how many patches you are indexing, creating the index on first launch may take a while (anywhere from less than a second to several seconds on modern hardware), so changing these options *will* have an impact on startup times. If Purr Data seems to launch slowly, being stuck in index generation, and you rarely use the help browser, then you want to make sure that the "prepare the help index at application start" option is unchecked (which is the default). On the other hand, if you're using the help browser very frequently and it seems to come up very slowly on first launch, you may want to check that option so that index creation is already done after launching the program.
There are two options which let you change the scope of indexed patches:
- If "help browser only searches the doc folder" is checked (which is the default), then keyword searches are confined to the doc/ hierarchy. This is the fastest option and will be sufficient for novice users at least, as it covers all the official documentation that ships with Purr Data. However, if you're an expert user and frequently use 3rd party externals living in the extra/ hierarchy, then you may want to uncheck this option to have all the remaining subdirectories in the pd-l2ork library directory indexed as well (note that this may slow down indexing considerably).
- The "help browser also searches the help path" option, when checked, lets you tailor the keyword search to the externals you're working with, so that you won't be swamped with keyword matches from externals you never use. These externals may be located anywhere you choose, including the extra/ hierarchy (e.g., if they're distributed with Purr Data), but note that if you've already unchecked the "help browser only searches the doc folder" option, then all the externals in extra/ will be searched anyway, so there's no need to also add subdirectories of extra/ to the help path. In either case, you'll have to add the directories to be searched to Purr Data's *help path* (having them in the library search path is *not* enough). You do this using Purr Data's `-helppath` option which can be added to the "startup flags" field at the bottom of the Startup tab. E.g., on Linux you may want to add something like `-helppath ~/pd-l2ork-externals` (that directory is often used on Linux for custom and personal external collections).
**Caveat:** Again, be warned that changing these options and then installing external collections with gazillions of patches into either the extra/ hierarchy or on your personal help path may have a very negative impact on startup times, since all these patches will have to be scanned during index creation. Future Purr Data versions will hopefully provide some form of persistence and incremental updates of the search index to mitigate these effects. But for the time being, judicial use of the above options should in most cases give you a sensible setup which does not slow down index creation too much while fulfilling your documentation needs.
Also note that because the search index is created either during program startup or when the help browser is first launched, changing any of the help browser configuration options normally requires a restart of Purr Data to take effect.
## Pd-l2ork and Purr Data Goodies
Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the [PdCon 2016 paper](http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf) for details. The paper also covers the history and motivation of the Pd-l2ork project.
......
No preview for this file type
prefs-gui+startup.png

126 KB | W: | H:

prefs-gui+startup.png

179 KB | W: | H:

prefs-gui+startup.png
prefs-gui+startup.png
prefs-gui+startup.png
prefs-gui+startup.png
  • 2-up
  • Swipe
  • Onion skin
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment