[PD] [PD-announce] Pd FLOSS Manual Update pt 2

[Derek Holzer]

So here is part two!

The following chapters were newly created during the Book Sprint. We'd 
really like to see them come together, but we don't think they will be 
anywhere near ready before we decide to publish the version 1.0. Futher 
work on these chapters is also appreciated, but only after the chapters 
we have marked for inclusion in the 1.0 are complete. Writing, editing 
and proofreading on these chapters can continue as normal, and when we 
are ready for a second release (now with GEM + SENSORS!) then we will 
include them.

CHAPTERS FOR FURTHER DEVELOPMENT, not to be included in upcoming 1.0 
release:

GEM
SENSORS
MIDI
NETWORK DATA

When the version 1.0 is completed, and these chapters are also fixed, 
then we can consider a paper publication!!!!!!

Here are the issues and places for improvement on each chapter. Again, 
we welcome improvements to these chapters, but if you are going to spend 
any time on this manual in the next few weeks, it would make more sense 
to focus on the chapters marked for publication (see Part 1 of this update):

____GEM_____

-> These chapters need a lot of work to be anywhere near complete!

-> My suggestion is to do more tutorial-based stuff, like "how to" 
sections, rather than break down the material by taxonomy (which is how 
it is already documented elsewhere). Thus, "How to VJ with Images and 
Video using GEM" and "How to Create 3D Animations using GEM" would be 
preferable to existing system.

-> Perhaps rather than single GEM heading, each of these could be 
section heading with chapters beneath them? In such a case, the chapters 
beneath each section should follow some logical progression from one to 
the other, leading towards the goal of VJing or doing animations.

-> Also some of the examples are far too complex, and rely on arcane 
systems like [import] or objects with severe nameclashes like [counter] 
which are traps for new users and should be avoided!

* http://en.flossmanuals.net/bin/view/PureData/GEMIntroduction
--Check for tone, perhaps more introduction and less credits, explain 
basic parts better (i.e. "2D and 3D graphics and animation, realtime 
image and video processing, and particles")
--Show screenshot of help patches + examples in Pd Browser?

* http://en.flossmanuals.net/bin/view/PureData/GEMBasics
--Mention "Red Book" and other technical OpenGL info later, it's not 
needed in beginners introduction, skip immediately to rendering
--Re: [gemwin] question in text ("is this true?"): please verify this 
information or cut it!
--In general, would be good to concentrate on doing things rather than 
exhaustively explaining technical details
--Re: [pix] objects.... save this for chapter on it.
--Perhaps what is needed here is overview of GEM functions, and then 
each chapter can deal with them independently as part of unified 
tutorials (VJing/Animation)
--Section (or new chapter) on setting up second screen for live 
performance for each OS!

* http://en.flossmanuals.net/bin/view/PureData/GEMImagesMoviesAndVideo
--This could really use less of reprinting helppatches, and more how to 
do things, like:
____Using [metro]/[float] counter to drive frame playback (changing 
playback speed or going backwards)
____Using [mod] and [+] to create smaller loops within film
____Use [random] to "granulate" film
____Use pix effects (where to insert in gemlist)(then refer to later 
chapter for more details, or work into single VJ tutorial as suggested 
above)
--Section on video formats for each OS is essential!!!!

* http://en.flossmanuals.net/bin/view/PureData/GEMVideoMixer
--I would like to see [alpha] plus [colorRGB] used in how to do simple 
crossfader instead of [pix_mix].
--Explanations could be helped more towards clarity.
--Re: recommendation to "create abstractions": either explain this 
inline or direct reader to Patch Management section (to be created) 
which will cover subpatches, abstractions, etc
--Webcam: needs Linux info on getting video devices in, there are 
probably other flags which need to be shown as well

* http://en.flossmanuals.net/bin/view/PureData/GEMPixEffects
--Please don't use a PiDiP object [colorgrid] in a GEM tutorial!!!!!!! 
(Also not cross platform!)
--Can this tutorial be done without need to import? (i.e. used normal 
counter instead of external?) I really don't agree with using objects 
that have such bad name clash issues, like [counter]
--The [send] and [receive] are abbreviated (first bad) and not explained 
in tutorial (second bad)
--In general, examples are too complex, please simplify!!!!!!!!!

* http://en.flossmanuals.net/bin/view/PureData/GEMSavingAndRecording
--Same problem as above, please don't [import] as it makes it much more 
complicated to explain whole patch. Basic objects available in 
Pd-Extended are assumed, anything else should either be skipped or 
extensively explained in line!
--While the toggle for turning gemwin on and off is useful, it is not 
explained in line and in general adds unneeded complexity to example 
patch. please simplify!
--If this section is about [pix_record] then it would be best to focus 
on that object and leave fancy stuff out

* http://en.flossmanuals.net/bin/view/PureData/GEMScreens
--Good place for second screen tutorial?
--Per OS instructions with screenshots please!

* http://en.flossmanuals.net/bin/view/PureData/GEMBlueGreenScreen
--Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMVideoTracking
--Good start but nowhere near complete. need to see more screenshots of 
video tracking at work, more real world examples
--I think list at the end is far far far too ambitious for beginner's 
manual! (pattern recognition (TUIO), pix_opencv (face recognition), 
blobs and multiblobs, IR illumination and multitouch technology)

* http://en.flossmanuals.net/bin/view/PureData/GEMText
--Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMInteraction
--Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMFrameBuffer
--Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMGLSLShaders
--Not much there, and I really consider this far too advanced for a 
beginners manual. This chapter should be sidelined until absolutely 
every other topic in GEM has been well covered.

* http://en.flossmanuals.net/bin/view/PureData/GEMdShapes
--Nothing there
--Suggest to merge shapes and animations and some others into general 
chapter on how to do animation in GEM

* http://en.flossmanuals.net/bin/view/PureData/GEMdAnimation
--Nothing there
--See GEMdShapes notes

* http://en.flossmanuals.net/bin/view/PureData/GEMCamera
--Nothing there
--Low priority for now
--See GEMdShapes notes

* http://en.flossmanuals.net/bin/view/PureData/GEMLightingFogAmbientColor
--Nothing there
--Low priority for now
--See GEMdShapes notes

http://en.flossmanuals.net/bin/view/PureData/GEMParticleSystems
--Nothing there
--Low priority for now
--See GEMdShapes notes

____SENSORS____

-> Suggest renaming chapter to external inputs, and including MIDI, 
[key] etc

* http://en.flossmanuals.net/bin/view/PureData/GameControllers
--The [cursor] object has nameclash!!!!!! Which lib? Please avoid libs 
which need [import] or have nameclash!
--Would it be possible to simply open [hid] help file to start with, 
then explain furhter down how to code it from scratch?
--The "minia" HID device is rather obscure hardware which most people 
will never have. Possibly move it + finished controller shown to some 
later section that shows people's custom controllers projects, rather 
than use as example
--This chapter could use some better attention, clearer explanations, a 
"how to" 1, 2, 3 rather than current structure. For example, how to plug 
in Wingman and control very simple synth!

* http://en.flossmanuals.net/bin/view/PureData/Pduino
--Good start, but needs work clarifying.
--Section on installing the Pduino library needed for each OS
--Section on installing Arduino needed for each OS
--Section on getting USB serial emulation needed for each OS
--Screenshot of "open button" should include submenus
--One screenshot uses [pd display values without pegging the CPU] 
subpatch, which is not explained nor made available. Please avoid this, 
or explicitly have them open the [pduino] abstraction
--Please make circuit diagram and spend some time explaining the circuit 
(i.e. tell what voltage divider is and how it works)
--Re: [autoscale]: what lib is this? Is it in Pd-Extended by default or 
must it be imported. In general, it would be nice to use some basic 
maths there instead for simplicity, since we can't assume reader knows 
what [autoscale] will do.
--Best to explain patches in-line as well as in patch comments. In-line 
text can be text-searched in browser or PDF reader, while comments in 
images cannot.
--Perhaps also better explanation of [send] and [receive], or direct 
reader to chapter on it.

____MIDI____

* http://en.flossmanuals.net/bin/view/PureData/UsingMidi
--This chapter needs some serious work. Again, there is more taxonomy 
here than tutorial.
--I would like to see following:
____Intro to MIDI hardware
____How to set up system for each OS (See Configuring PD chapter)
____Tutorial showing how to plug in keyboard and get notes from proper 
channel
____Tutorial on how to plug in fader box and get CC info on proper channels
____Tutorial on how to send MIDI from Pd to other apps (FLOSS apps, if 
possible)(using IAC bus on OSX, MidiOx or similar on Windows and 
QJackCTL on Linux)
--The "pd uc16" example screenshot is needlessly complicated, and 
graphical bangs like that should be discouraged as they would cause 
audio glitches on many users' systems if data came in quick enough

____NETWORK DATA____

* http://en.flossmanuals.net/bin/view/PureData/Receive
--Needs a lot of work!!!!
--Please real world examples rather than taxonomy

* http://en.flossmanuals.net/bin/view/PureData/OSC
--Please use built in OSC as default, since those are what comes out of 
the box in Pd Extended, are the simplest and also still the most widely used
--If you want to use mrpeach objects, please do this in a separate 
section or chapter (Advanced OSC, perhaps?) and please be sure to 
explain in-line how to load non-standard externals (see Configuring Pd 
chapter, perhaps best to put it there are reference it)

Thanks again to everyone who helped out over the weekend, and let's all 
get busy making this manual the best it can be.

Best wishes from Berlin!
Derek

-- 
::: derek holzer ::: http://blog.myspace.com/macumbista ::: 
http://www.vimeo.com/macumbista :::
---Oblique Strategy # 113:
"Make a blank valuable by putting it in an exquisite frame"

_______________________________________________
Pd-announce mailing list
Pd-announce at iem.at
http://lists.puredata.info/listinfo/pd-announce