() Panicz Maciej Godek <godek.maciek@gmail.com>
() Mon, 6 May 2013 21:36:33 +0200

   Thanks :) I see that there are a few persons with similar ideas, and
   I wonder how powerful we'd become if we managed to orchestrate our
   powers somehow, as TTN suggested

Orchestration is a nice concept.  It is the marshalling of separate
efforts in a parallel direction (towards the audience), moderated
individually, but w/ group awareness, by precise changes in timing and
pitch.  Cool.

For this, i strongly urge everyone who wants to jam[0] to provide
documentation.  That is the minimal requirement, the tuning of your
instrument so that it does not burn the ears of others seated beside
you.  So what if you don't have (the autotools) rhythm?  That can (and
must!) be cyclically attained.  To start, you gotta have the right Hz.

"But ttn, documentation is a pain to create and maintain!"

Well, yes.  For creation, i offer as riposte Guile-BAUX[1], which helps
me painlessly convert:

--8<---------------cut here---------------start------------->8---
  PRIMPROC
  (mix_allocate_channels, "allocated-channels", 1, 0, 0,
   (SCM numchans),
   doc: /***********
  Dynamically change the number of channels managed by
  the mixer to @var{numchans}.  If decreasing the number
  of channels, the upper channels are stopped.  Return the
  new number of allocated channels.  */)
  {
  #define FUNC_NAME s_mix_allocate_channels
    ASSERT_INTEGER (numchans, 1);
  
    RETURN_INT (Mix_AllocateChannels (C_LONG (numchans)));
  #undef FUNC_NAME
  }
--8<---------------cut here---------------end--------------->8---

and

--8<---------------cut here---------------start------------->8---
  ;; Return the exact truncation (rounding to zero) of @var{number}.
  ;; This is ``safer'' than simply @code{inexact->exact}
  ;; for some Guile versions.
  ;;
  ;; @example
  ;; (define scale 0.180281690140845)
  ;; (inexact->exact scale)
  ;;   @result{} 3247666210160131/18014398509481984 ; Guile 1.8.7
  ;;   @result{} 0                                  ; Guile 1.4.x
  ;; (exact-truncate scale)
  ;;   @result{} 0
  ;; @end example
  ;;
  (define (exact-truncate number)
    (inexact->exact (truncate number)))
--8<---------------cut here---------------end--------------->8---

into:
<http://www.gnu.org/software/guile-sdl/manual/html_node/Audio.html#index-allocated_002dchannels>
and
<http://www.gnu.org/software/guile-sdl/manual/html_node/Miscellaneous-Utilities.html#index-exact_002dtruncate>
respectively.

The nice thing (IMNSHO) is that Guile-BAUX is itself a nontrivial chunk
of Guile Scheme, nothing more, and furthermore takes pains to rise above
the cacaphony of Guile version-specific quirks.

Documentation maintenance, on the other hand, is a charge laid squarely
on the Author and the Author's discipline and astuteness.  You know what
to do; you know how to do it; what must be dredged from the void is the
will and the practice, the mind and the motion.  I wish you fortitude.

_________________________________________________________
[0] http://www.merriam-webster.com/dictionary/jam
    (as in "jam session")

[1] http://www.gnuvola.org/software/guile-baux/

-- 
Thien-Thi Nguyen
GPG key: 4C807502