Re: [Vxl-maintainers] CVS->subversion complete

[Matthew L. <mat...@gm...>]

On Mar 19, 2009, at 3:17 PM, Amitha Perera wrote:

> I am wondering if we should just pick LaTeX (and therefore PDF), and  
> not bother with the HTML.  Given that it is a "book".
>
> But, like the Subversion book and the CVS book, having an HTML  
> version may be useful.
>

I see no reason to port everything from texinfo to LaTeX.  I think  
it's nice to have an HTML version.  In fact, I've never even looked at  
the PDF version.  When I was learning VXL I read the whole book in  
HTML.  I think the HTML version would be even better if we could apply  
some CSS to make the formatting a little easier on the eye.

My biggest concern with texinfo is that is requires a build process  
and is often out of date.  Plus it is more complicated for the average  
developer to edit.

I think we should either keep the book in texinfo as it is, or replace  
it with two parts:
1) A wiki that provides some of the same information, but not in  
"book" form.
2) A "real" book in LaTeX form, maybe more like a textbook. This idea  
has come up before.

I think we ultimately need three things for documentation
1) an FAQ for things like obtaining source code, compilation, how to  
do simple tasks, as well as overall design concepts for VXL  (wiki  
would be good for this)

2) A library design overview explaining the general concepts of each  
library and the appropriate way for developers to extend each library.  
(Doxygen intro pages are good for this)

3) A tutorial or textbook on how to use VXL, maybe with examples of  
real vision problems (This is probably where the LaTeX book for print  
comes in).

Matt