Re: [Sndobj-devel] sndobj/PySndObj manuals

[sonify <so...@av...>]

If code is changing, issues of  application/code version  
compatibilities need to be addresed up front.

Perhaps a brief discussion might be appropriate before making a  
decision.

My own preference is to have the manual distributed w. the code.
That encourages keeping documentation to be kept up-to-date as  
changes to the code occur.
Also fits into sourceforge/CSV structure seamlessly.

_PDF's_ print well but do not encourage modularisation and hot-linking.
Ditto _msword _(.doc) but they are not as big and are easier to edit.

_HTML_ can be a pain to edit but templating can encourage consistency  
for a better look and feel.
Apart from the (currently excellent) introductory material, there  
seems to be no one appropriate linear
presentation of the material. What is important is that related stuff  
can be found. This to me means hyperlinks.
Not that it's the be-all and end-all, but the (online) documentation  
for python works well IMO and we could do worse.

An HTML manual can more easily be browsed on-line and I would have  
thought  that would encourage new users.

_OpenOffice_ functions (in this context) like msword. It can open ms  
word docos but not sure about the
other way around. Can save to PDF and HTML. HTML tools look better  
than msword. Is is not as widely used as msword.

I've no desire  to reinvent the wheel, Victor. Perhaps we could  
experiment with some samples that export
to html? Seems simple, but would depend on how "fancy" you want it.  
My preference is for simplicity,
clarity, ease of use over "bells and whistles".

Thoughts? I'd be happier if we did some experiments before committing  
to any one solution, unless you think it's clear.
I'm not in a busting hurry, so if you want to make your updates  
first, that's cool. I just ned to " put it on the scheduler stack" :-)

David


On 20/01/2007, at 8:37 PM, Victor Lazzarini wrote:

> I'll try and import the manual sources (they are
> all MS-Word docs) and then you can work on them,
> if you'd like.
>
> The manual used to be html, but then I moved it to
> MS-Word because I found it easier to maintain and to
> create PDFs.
>
> Please post the e-mail re importing modules.
>
> all the best
>
> Victor
>
>>
>> It is interesting to note the current discussion about
>> manual and   versions and dates on CS-dev.
>>
>> A 'wild' discussion about manuals and documentation is
>> also currently   occurring on supercollider-dev.
>> Must be something in the water. :-)
>>
>> May I suggest an on-line (html) manual for sndobj ....
>> and a   separate one for PySndObj ?
>>
>> I'd be happy to work, over time, on the latter. It's
>> currently   exellent if you know what you're doing,
>> however I do think it could be made a bit less daunting
>> for those less   experienced.
>>
>> Victor, re the correspondence  we had about python's from
>> "import x"   c f "from x import *", I've had some
>> correspondence with the mac-  python SIG 's Piet Oussoren
>> (well known in those parts)  and he has   provided a
>> detailed discussion. I'll post/email it if anyone's
>> interested.
>>
>> ciau,
>>
>> Davud
>> _________________________________________________
>> experimental polymedia:    www.avatar.com.au
>> Sonic Communications Research Group,
>> University of Canberra:
>> www.canberra.edu.au/vc-forum/scrg vip=Verbal Interactivity
>> Project
>>
>>
>>
>>
>> ----------------------------------------------------------
>> --------------- Take Surveys. Earn Cash. Influence the
>> Future of IT Join SourceForge.net's Techsay panel and
>> you'll get the chance to share your opinions on IT &
>> business topics through brief surveys - and earn cash
>>
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV
>> _______________________________________________
>> Sndobj-devel mailing list
>> Snd...@li...
>> https://lists.sourceforge.net/lists/listinfo/sndobj-devel
>
> ---------------------------------------------------------------------- 
> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to  
> share your
> opinions on IT & business topics through brief surveys - and earn cash
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Sndobj-devel mailing list
> Snd...@li...
> https://lists.sourceforge.net/lists/listinfo/sndobj-devel
>

_________________________________________________
experimental polymedia:	www.avatar.com.au
Sonic Communications Research Group,
University of Canberra:	 www.canberra.edu.au/vc-forum/scrg
vip=Verbal Interactivity Project





_____________________________
David Worrall: so...@av...