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

[Daniel Brockman]

address@hidden (Daniel Jensen) writes:

> Daniel Brockman <address@hidden> writes:
>
>>    ``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?''
>
> That is a good question. What kind of hacking or hacking-related
> information is it that you want described in a manual?

Take this part from my draft:

   ``Bongo buffers may contain any arbitrary text, but the
   interesting thing about them is that they can contain
   tracks and sections of tracks (and sections of sections).
   Tracks are special lines whose appearance is controlled
   by Bongo.  Most tracks correspond to the name of a local
   media file or the URL of a media stream, but there are
   other kinds of tracks as well.

   ``While track lines have special significance to Bongo,
   they are really nothing more than lines of text with some
   special properties on them.  As such, track lines may be
   killed and yanked freely, both within a single buffer and
   between different Bongo buffers.''

It's almost too detailed for users, but at the same time too
vague to be really useful for someone hacking on Bongo.

Maybe we can solve that by writing a detailed account of how
track lines work in a separate section and cross-referencing
it with the one focusing on how to _use_ track lines.

   ``While track lines have special significance to Bongo,
   they are really nothing more than lines of text with some
   special properties on them (see Track Lines).  As such,
   they may be killed and yanked freely, both within a
   single buffer and between different Bongo buffers.''

Then, in the Track Lines node, something like

   ``Depending on the type, a track line is a line with
   either a `bongo-file-name' or a `bongo-action' property,''

and so on.  Nodes like this could describe Bongo functions and
variables not normally interesting to users, and so the manual
would have an index that would be very useful to developers.

We can collect the hacker-oriented reference material under
some heading that lets users know they don't have to read it.

I guess that's a middle-way answer to my original question ---
``should we have separate user and hacker manuals?''

> Writing a custom backend?

I'd say that almost counts as an advanced user-level topic;
including it as a separate section is unproblematic anyway.

>> Basically, then, the beginning of the manual should be a
>> more detailed version of the initial Bongo buffer text:
>
> By the way, should it be possible to turn the initial
> buffer text off?

Yes.

>> How about this for a start?
>>
>>  * Overview [...]
>>  * Inserting Tracks [...]
>>  * Playing Tracks [...]
>>  * Library Buffers [...]
>>  * Saving
>
> Looks good. I'd also like to see a node on customizing Bongo.

Good idea.

> Then there are other special topics, like marks.

Ditto.

> Now, we have three available manual writers, correct?

Yes.  Thanks for volunteering.

> Do you think it can be coordinated now, or will it take
> time to get going?

I don't know what the holdup would be.  I'm currently a bit
starved for time, so don't expect any grunt work contributions
from me at least until the end of the week.

I don't see any problem with just grabbing a topic and
writing about it.  I think Romain has some collaborative
manual writing experience so he might disagree.

>>> 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.
>
> I see your point, but I don't think the software is that relevant.
> (And not because it actually is free software.) The database is the
> primary issue, because that's what Bongo uses.

Yeah, I was using `software' in the Debian sense.

> However, I think we can save this discussion for later
> when Emacs 22 is finally out.

Okay.

-- 
Daniel Brockman <address@hidden>