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

[Eric Blossom]

On Tue, Jul 18, 2006 at 12:44:08AM -0700, Jan Schiefer wrote:
> 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?

Looks like we're making progress in that direction ;)

> 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.

Agreed.  

With regard to Windows, unless some Windows programmers step up to do
the work, I don't think we'll ever end up very polished on that
platform.  Martin and Stephane have done good work getting it to work
under MinGW and Cygwin, but neither of them are windows users.  [We
could be seeing a cultural difference here.  Folks from the free
software world understand that software gets written by people, not by
some abstract "company" located someplace else.  If the hypothetical
GNU Radio windows users keep waiting for somebody else to do it, it'll
most likely never get done.]

> 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)

Sounds reasonable.  I think I'd consider this the minimum set:

  gnuradio-core, gnuradio-examples, gr-audio-<appropriate>, usrp, gr-usrp, 
gr-wxgui

regardless of whether they had a usrp or not.  I expect that at some
point in the future we'll have a gr-pyqtgui, and then we'll see how the
two GUI options compare.

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

Seems reasonable.

> 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'm not aware of anyone currently working on a .rpm distribution.
Ramakrishnan has been generating Debian .debs for the past few years.
I'd love to have .rpms, if somebody is willing to generate and test
the .spec files on say, SuSE 10.*, Fedora Core 5, and perhaps Mandriva
200{6,7}

> 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.

Actually, I think that most people use emacs, of course ;)
There are a couple of docbook modes to choose from...

I'd definitely stay away from using OpenOffice to generate docbook.
I'm not familiar with Vex, let us know how it works out.

> Cheers,
>    Jan

Thanks again for all your input and ideas.

Eric