Re: [Sndobj-devel] sndobj/PySndObj manuals

[Victor L. <Vic...@nu...>]

Well, code changes, but compatibility has been so far
maintained and I feel this is the way to do things.

I think doing a html manual could be a good thing, but
I'd like to maintain a way of making PDFs with table of
contents for printing, to which pages can be added easily.
The MS Word version of the manual has worked for me
quite well in that respect. I might investigate moving it
to open office so we have a Free software base for
everything.

But that does not stop the manual being made html; the
only thing is that we would have to synchronise the
updates.

The way Csound5 has worked in the past ears is to use
XML and docbook to make the manual. But I'm really no keen
on writing XML, which I find a pain. However, if this is
found to be the best way, I can go with it. I'll have to learn
a little more about it though.

Victor


t 06:06 21/01/2007, you wrote:
>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
>
>
>
>
>-------------------------------------------------------------------------
>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

Victor Lazzarini
Music Technology Laboratory
Music Department
National University of Ireland, Maynooth