Re: [bongo-devel] Re: Bongo in Emacs 23

[Daniel Brockman]

address@hidden (Daniel Jensen) writes:

> Daniel Brockman <address@hidden> writes:
>
>> Just so you don't think I'm holding out on you, here is the
>> stuff I wrote before.  Please consider it very much a draft,
>> please don't hesitate to criticise or change any aspect of it.
>
> I have a few ideas and some criticism. It's a good start,
> though maybe a little wordy.

Thanks.  I should get out of the habit of trying to phrase
my paragraphs to fill nicely, at least when I don't really
have any control over the filling (as in a Texinfo file) ---
that may have played a part in making it unnecessarily wordy.

> Please have this in mind, from the GNU coding standards:
>
>     Programmers tend to carry over the structure of the program as the
>     structure for its documentation. But this structure is not
>     necessarily good for explaining how to use the program; it may be
>     irrelevant and confusing for a user.
>
>     Instead, the right way to structure documentation is according to
>     the concepts and questions that a user will have in mind when
>     reading it.

Good point.  I actually did consider that problem, and it
was part of the reason why I didn't send the text earlier.

Here's from an old unsent draft message to bongo-devel:

   ``Should we have separate user and hacker manuals --- the
   same distinction as that made between the GNU Emacs Manual
   and the GNU Emacs Lisp Reference Manual?

   ``If not, how do we include the details useful for hackers
   without cluttering the manual too much for users?''

> It would be good to begin the manual with sections on
> starting Bongo, inserting tracks and playing tracks.
> That is the basic usage of a media player.

I agree.  Just to be clear, I didn't particularly try to
write an introduction when I wrote the text on buffers ---
but looking at the text I suppose it sort of seems I did.

I couldn't help it, because whatever I wrote it was
unavoidably the very first text in the manual. :-)

Maybe I should have specifically tried to write an introduction.

> It could even be a straight tutorial at the start.
> Then we can go on explaining the details.

Basically, then, the beginning of the manual should be a
more detailed version of the initial Bongo buffer text:

   Welcome to Bongo, the buffer-oriented media player!
 
   This is a Bongo library buffer.  It's empty now, but in a
   few moments it could hold your entire media collection ---
   or just the parts that you are currently interested in.
 
   To insert a single local media file, use `i f'.
   To insert a whole directory tree, use `i t'.
   To insert the URL of a media file or stream, use `i u'.
 
   To enqueue tracks in the nearest playlist buffer, use `e'.
   To hop to the nearest playlist buffer, use `h'.

   ---------------------------------------------------------
  
   This is a Bongo playlist buffer.  It holds things that are
   about to be played, and things that have already been played.

   To start playing a track, use `RET'; to stop, use `C-c C-s'.
   To play the previous or next track, use `C-c C-p' or `C-c C-n'.
   To pause or resume, use `SPC', and to seek, use `s'.

   You can use `i f', `i t' and `i u' to insert things directly
   into playlist buffers, but enqueuing (using `e') from library
   buffers is often more convenient.  Use `h' to hop to one.


That text is very economically phrased, but I think it does a
good job of mentioning the most important things first.

> I think you should create an outline of the topics that a
> user would want to read about.

How about this for a start?

 * Overview

   This section would introduce some basic concepts
   necessary to understand how Bongo works.

    - Buffers
    - Tracks
    - Backends

 * Inserting Tracks

    - File Tracks

      This section should talk about the file name
      patters Bongo recognizes for metadata.

    - URI Tracks
    - Audio CD Tracks
    - Action Tracks

 * Playing Tracks

   This section would discuss playback commands and the
   way in which playback proceeds in a playlist buffer.
   
    - Pausing
    - Seeking
    - Volume Control
    - Last.fm

 * Library Buffers

 * Saving


>>> Will the Last.fm support go in, too?  (It's a non-free service.)
>>
>> I don't know what the general opinion about Last.fm is among
>> free software advocates.
>
> My opinion is that a web service does not have to use free software
> for me to use it. It is impossible to verify and it has no practical
> implications to me anyway.

The point is not whether it _uses_ free software, but rather
whether the software it _distributes_ is free.

Last.fm distributes player software, which indeed is free.

But it also distributes raw data collected from users ---
this data it distributes under CC-NC-SA.

>> Are there any similar services which exhibit a friendlier
>> attitude towards software freedom?
>
> MusicBrainz is a free music database, although I don't
> know if it has a scrobble feature.

Its article on Wikipedia does not say anything about a
scrobble feature.

Here's what it says about licensing:

   ``MusicBrainz's core data (artists, tracks, albums, etc.) is
   in the public domain, and additional content including
   moderation data is placed under the Open Audio License
   (which is a Creative Commons non-commercial
   share-and-share-alike license).  The server software is
   covered by the GNU General Public License. However,
   MusicBrainz uses a binary version of the Relatable TRM
   server, of which the source code is proprietary. The
   MusicBrainz client software library, TunePimp, is licensed
   under the GNU Lesser General Public License, which allows
   use of the code in proprietary software products.''

So it basically doesn't seem any different from Last.fm.

> However, it might be something that can be combined with
> Bongo anyway.  I've been thinking about a feature that
> would fetch information and an album cover from some web
> site while you're playing music.

Yeah, that sounds interesting.

-- 
Daniel Brockman <address@hidden>