Re: [Discuss-gnuradio] Secret documentation and Python 2.4

[Jan Schiefer]

Hi Eric,
> This particular nugget of info is secreted in gnuradio-core/README ;)
>
>   
I had long given up on README files, as I found them to mostly contain 
trivial stuff. Maybe it is time to revise that policy :-).
> > Seems like this thing is a little underdocumented. How can we help?
> >     
>
> would be most welcome.  Part of the problem you're seeing is that
> folks have generated documentation outside of the project (no problem
> with that), however, since it's not in our repository, we can't edit
> it to make corrections, extensions, etc.  Besides Naveens's, we've got
> the same problem with Dawei Shen's tutorial.
>   
Any chance that the authors of this external documentation might be 
talked into contributing it to the docs module?

Let me ramble a bit about the potential "customers" for more 
documentation. Gnu Radio is really a great technology and significantly 
lowers the barrier to entry to playing with SDR. However, the learning 
curve is still pretty steep. Particularly as not everybody has the 
knowledge or patience to resolve all the build dependencies, or the 
money to buy an USRP. I am thinking of e.g. some hams that may have a 
Windows PC, a little dusty programming knowledge but some exposure to 
DSP concepts and plenty of motivation. The kind of motivation that you 
get from reading the "Exploring GNU Radio" article. But there is a big 
gap to "How to write a block". We are still very much in early-adopter 
land here, and getting more people playing with this stuff would make a 
big difference.

So if there was this hypothetical binary distribution, I think it might 
look like this:
- gnuradio-core and audio-support in binary form, to be installed on top 
of an existing Python install
- Optional USRP support
- A few How-Tos: Getting started (mini-Python primer, mini-SDR primer, 
Running your first example program, Catalog of the existing examples, 
Audio experiments involving your favorite MP3, Radio experiments with 
downloadable waveform snippets, etc)
- An easy ordering option for USRPs :-)
- Commented/documented examples
- The secret gnuradio-core library docs as HTML (or CHM on Windows)

Basically, documentation for anything that you can do without a C++ 
compiler, with a focus on How-Tos, examples and ideas for experiments.

Does this make sense? Or am I barking up the wrong tree here? If so, any 
other ideas on where to focus?

Also, does this hypothetical binary distribution exist, or is somebody 
maybe working on it?

I haven't used docbook, but it doesn't exactly look like rocket science. 
Any recommendations on authoring tools? (Please, let the answer not be 
"Emacs, of course!"). Vex looked pretty promising, OpenOffice didn't 
seem to offer much support.

Cheers,
   Jan