[EMAIL PROTECTED] (Daniel Jensen) writes: > Daniel Brockman <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> _______________________________________________ bongo-devel mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/bongo-devel
