[prev in list] [next in list] [prev in thread] [next in thread] 

List:       arts
Subject:    Re: aRts Documentation
From:       Stefan Westerfeld <stefan () space ! twc ! de>
Date:       2001-01-02 16:53:46
[Download RAW message or body]

   Hi!

On Sun, Dec 24, 2000 at 10:48:11AM -0500, Jeff Tranter wrote:
> I'm planning to start working on improving the aRts documentation.
> I'd like to outline my proposal and get feedback on it before I
> start.  What I envision is:
> - one manual for aRts, including artsbuilder and utilities
> - in the standard KDE docbook format
> - will go in CVS in kdemultimedia/docs/arts
> - will eventually replace the existing documentation
> - we can also put it on the aRts web site
> - based on material from:
>   - aRts 0.3.x manual
>   - artsbuilder manual in kdemultimedia
>   - misc. docs in kdelibs/arts
>   - additional new material

Overall, that sounds like a good plan. You can use the already docbook
converted manual in kmusic as starting point. For the APIs, a consideration
might be using kdoc for autogenerating at least some kind of reference. It
should work on both, C++ headers and IDL files.

Your outline covers about everything. There are some parts you refer to that
are not available in the current version. It would probably be best not to
mention something in the manual that does not (yet?) exist.

- publishing
- autoloading at startup
- mixers

Addionally, I would replace ARts with aRts (don't like the double-
capitalization).

As for the order of things - if a new user reads the manual starting with
the first chapter, and then reads on, he will probably get thouroughly
confused in the "aRts in Detail" section. Usually, the learning curve
will probably look like

1. soundserver user: runs artsd, artscontrol, and various applications
2. user gets in touch artsbuilder, tries to understand what it does, and
   tries to do instruments and effects with it
3. developer: implements modules in C++, writes applications like noatun,
   brahms,...
4. core developer: tries to extend aRts infrastructure, like adding video
   streaming, threading or timestamping   OR  works on a compatible MCOP
   implementation, that doesn't use the aRts libraries

Ok, that is of course just an approximation what people will do. But the
tricky thing will be safely getting interested people at least to 2.,
without scaring them away with things like details about the Trader or
the MCOP protocol specification ;).

   Cu... Stefan
-- 
  -* Stefan Westerfeld, stefan@space.twc.de (PGP!), Hamburg/Germany
     KDE Developer, project infos at http://space.twc.de/~stefan/kde *-         

[prev in list] [next in list] [prev in thread] [next in thread]