[Insight-developers] My experiences with ITK SoftwareGuide

[Jisung Kim]

Hi.

I have some questions and suggestions about the ITK
SoftwareGuide development.

=========================

Some questions:

1. exporting TEXTINPUT evironment variable.

  LaTexWrapper.sh (or LaTexWrapper.bat) file looks
like exporting the TEXTINPUT variable with
SoftwareGuide specific paths. However, when the build
process begins to generates pdf file, it complains
about eps files (it couldn't fine those files). After
I add those paths in my profile, it works okay. Am I
doing something wrong?

2. Latex reports pool size overflow.

  I didn't have this problem, when I build the
SoftwareGuide on my Red hat desktop (ver. 8.0). Then I
switched my workspace to my laptop that has debian
testing release. Then I had this problem. I solved(?)
this problem by increase the pool_size(125000 to
200000) and the max_strings (15000 to 30000) in my tex
distribution's /usr/share/texmf/web2c/texmf.cnf. I'm
wondering why a larger pool is reguired. Is it because
there might be some mistakes in the tex source files,
or because the SoftwareGuide requires that much?

3. cygwin environment

  I had the problems mentioned above on my cygwin
setup. And the makefile in the SoftwareGuide/Latex
directory seems to use the LaTexWrapper.bat instead of
LaTexWrapper.sh. Because of this, when I tried to
build the SoftwareGuide using the same binary
directory in my Linux setup on the same machine, it
failed. Is there any reason to use .bat file on
cygwin? I also found that some paths in the
CMakeCache.txt that had been genereated on cygwin use
window path names.

4. Changes in the examples don't trigger the build
process.

5. How to create a hypertext link to doxygen
documentation for namespaces other than itk

  The \doxygen{class name} macro creates hypertext
links. However, I couldn't create such links for the
statistics related classes in the "itk::Statistics"
namespace. I created a macro for this specific case. I
use it like: \subdoxygen{Statistics}{ListSample}. It
only supports one level down. I heard that there are
ways to implement a macro using optional arguments.
Any good solution for this situation?

===================================
  
Suggestions

1. minimizing interaction with multiple CMakelists.txt
files.

  To add examples and xfig graphics to the
SoftwareGuide, I have to manage at least four
CMakeLists.txt files: 
SoftwareGuide-source/Latex/CMakeLists.txt, 
SoftwareGuide-source/Example/CMakeLists.txt,
SoftwareGuide-source/Art/CMakeLists.txt, 
and Insight-source/Examples/Statistics/CMakeLists.txt.
  

  Using a perl script, we might be able to search for
.cxx files and .fig files in the SoftwareGuide/Art
directory and Insight-source/Examples and update the
CMakeLists.txt files.

2. Add an option that allows developers to build
chapter by chapter instead of the whole documentation.

  For the development phase, I think it might be
useful because it reduce the build time, and I can use
some emacs tools such as preview-latex that shows the
section titles, equations, graphics, and tables close
to their final forms. 

==========================

I'm not a TeXnician and try to reuse other peoples
work. However, I think the size of the SoftwareGuide
and the complexity of its configuration make the
documentation development process slow.

Any thouhts on this subject?

Thank you,  

=====
Jisung Kim
bahrahm@yahoo.com
106 Mason Farm Rd.
129 Radiology Research Lab., CB# 7515
Univ. of North Carolina at Chapel Hill
Chapel Hill, NC 27599-7515

__________________________________
Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo.
http://search.yahoo.com