[Insight-developers] My experiences with ITK SoftwareGuide
Luis Ibanez
luis.ibanez@kitware.com
Sun, 11 May 2003 15:09:17 -0400
Hi Jisung,
Thanks for your detailed report on the efforts required
for building the SoftwareGuide.
1) Yes, we also found that TEXINPUT has to be set
explicitly. I actually end up setting it in the
.cshrc file. The latex wrapper shell script was
intended to avoid this configuration, but we found
easier just to set the environment variable.
2) Thanks for letting us know about the
pool_size and max_strings limits. I don't know
why this is necessary either, but reducing the
amount of error messages when building the PDF
file is certainly convenient.
3) I made a couple of tries to build the guide
under cygwin. However, as you pointed out,
there are a number of difficulties originated
in the dual behavior of cygwin, where it is
like Unix for some things, but behaves like
windows for some others. My personal opinion
is that it is so easy to do this on Linux and
so hard to do it in cygwin that it is hard to
justify the effort. In practice I always built
the guide under Linux.
4) Changes in the examples do trigger the build
process in my build. Note that if you add
new examples, you have to manually edit the
CMakeLists.txt file in SoftwareGuide/Examples
in order to add them to the dependencies.
5) Yeap, \doxigen{} only works for the default
workspace. Your macro with one extra argument
sounds like a good idea for taking care of
this case. We don't have that many levels of
sub namespaces, so probably adding a third
macro with two namespace levels will take care
of most of the cases.
=============================
Your suggestions are all well to the point.
1) I agree with you in that it is anoying to
have to add the dependencies to the CMakeLists.txt
files. We could use a perl script as you suggested,
but we could go simpler by using the regular
expressions in CMake.
2) The option for building only selected chapters
is hacked now using a conditional in LaTex,
as opposes to a CMake variable. The way it works
is that in SoftwareGuide.tex there is a variable
itkFullVersion
You may notice that most of the \input commands
are surrounded with
\ifitkFullVersion
\input{fileXXX.tex}
\fi
you can basically disable all the sections by
setting
\itkFullVersionFalse
in line 74
and then commenting out the \ifitkFullVersion, \fi
only in the sections that you want to build.
This may seem a bit trickier, but result convenient
when you want to build only subsections of a full
chapter. Since you can comment out the if's at every
sub-level.
3) I aggree in that there is some complexity involved
in building the document. It is work to revisit that
CMakeLists.txt files and check for things that can
be improved.
Thanks
Luis
-----------------------
Jisung Kim wrote:
> 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
> _______________________________________________
> Insight-developers mailing list
> Insight-developers@public.kitware.com
> http://public.kitware.com/mailman/listinfo/insight-developers
>