[Insight-developers] First crack at usage documentation

[Sayan Pathak]

Hi,
Someone raised issues regarding documentation of equations. Currently the
latex equations are converted into gif files which is in my opinion ugly.
MathML is an emerging standard and looks like future browsers are moving
towards that direction. I am attaching a link that talks about where things
are with respect to MathML currently.
 http://www.w3.org/Math/

Click on "software" link, you will see a list of software that work with
MathML.

Check it out and could be a good one to get opinion of the group considering
a lot of these algorithms have a lot of documentation with equations in
them.

Sayan

-----Original Message-----
From: insight-developers-admin@public.kitware.com
[mailto:insight-developers-admin@public.kitware.com]On Behalf Of Will
Schroeder
Sent: Thursday, December 21, 2000 5:00 AM
To: spathak@statsci.com; insight-developers@public.kitware.com;
aylward@unc.edu
Subject: Re: [Insight-developers] First crack at usage documentation



Hi Folks-

Several people have contacted me regarding documentation. Stephen Aylward
sent me an outline describing a comprehensive documentation suite, and
Sayan Pathak and I talked about more extensive "class/group of classes
documentation" that he has just sent to the list. Bill Hoffman showed me
the vxl documentation which is arranged in the form of a book
(http://www.robots.ox.ac.uk/~vxl/book/) also see
http://www.esat.kuleuven.ac.be/~targetjr/www.robots.ox.ac.uk/vxl/.

My take from these discussions is that it is time to create an outline for
documentation, both in terms of the Insight/Documentation directory
structure, as well for the arrangement of web pages and other material. I
particularly like the idea of building a logical arrangement of material -
consistent in style and layout - that we produce as a"book" or "books."
With that in mind, I'd like to propose a strawman organization for the
documentation. I expect that this will not be completed until the end of
the third year, but if we can share the vision of the framework, it will
expedite the creation of this invaluable resource. (Aside- Kitware has on
its WA3 and in its proposal the task of organizing/helping create
documentation and training materials)

What I have in mind currently is to build three "books" - User's Guide,
Developer's Guide, and Algorithm Guide. I'd like to see
each less than 250  pages (although the algorithm guide may grow larger).
Issues: I'd also like to settle on a implementation (e.g., Word, etc.) that
can be used to create both a nice looking text as well as producing html.
I'd also like to adopt some styles that are reasonable consistent.
Suggestions?

Anyway, here's a rough outline. (Some of this material came from Stephen
Aylward.) Sayan is going to lead the discussion on documentation of Friday,
maybe we can talk about this then. I'd also like to hear suggestions,
criticisms, etc.

Will
------------------------


Book 1- The Insight User's Guide (lots of examples - in C++)
Chapter 1 - Introduction
	- What is Insight?
	- Organization
	- Additional Resources
Chapter 2 - System Overview
	- Hybrid Compiled / Interpreted Architecture
	- Generic Programming
	- Data Processing Pipeline
Chapter 3 - Getting Started
	- Overview
	- Get The Software
	- Installation
		a. Windows
		b. Unix
	- Running (Insight HelloWorld)
		a. Windows
		b. Unix
	- Testing
		a. The Quality Dashboard
		b. Running a Test
Chapter 4 - The Basics (lots of examples)
	- Smart Pointers & Reference Counting
	- The Object Factory
	- The Image Class
	- The Mesh Class
	- Creating a Data Processing Pipeline
Chapter 5 - Segmentation
	- Pick several important algorithms and demonstrate them via example.
		a. Class hierarchy
		b. Landmark implementations
		c. FEM implementations
		d. Adding your own
		e. etc.
Chapter 6 - Registration
	- Pick several important algorithms and demonstrate them via example.
		a. Pixel Labeling Class hierarchy
		b. Adaptive Surfaces Class hierarchy
		c. Adding your own
		d. etc.
Chapter 7 - System Interface
	- Image Class
	- Mesh Class
	- Process (Data) Objects
Chapter 8 - Language Bindings
	- Typeless C++
	- Tcl (example)
	- Python (example)
	- Java (example)



Book 2 - The Insight Developer's Guide
Chapter 1 - Introduction
	- Purpose
	- Organization
	- Additional Resources
Chapter 2 - CMake
Chapter 3- Reference Counting and Smart Pointers
Chapter 4- The Object Factory
Chapter 5 - Managing Pipeline Execution
	- The Update Mechanism
	- Streaming Data
Chapter 7 - Wrapping C++
	- Overview
	- XML Notation
	- Typeless C++ Layer
	- Tcl
	- Python
	- Java
Chapter 8 - Extending the Image Class
Chapter 9 - Extending the Mesh Class
Chapter 10 - Writing a Process (Filter) Object
	- Overview
	- Input Image / Output Image
	- Input Mesh / Output Mesh
	- Other
Chapter 11 - Testing the Software
	- The Quality Dashboard
	- Submitting a Dashboard



Book 3 - The Insight Guide To Algorithms
Chapter 1 - Introduction
Chapter 2 - Segmentation
Chapter 3 - Registration
Chapter 4 - Supplemental
	- Transformation classes
	- etc.


_______________________________________________
Insight-developers mailing list
Insight-developers@public.kitware.com
http://public.kitware.com/mailman/listinfo/insight-developers