[Insight-developers] Documentation: LaTeX, LyX and HTML

[Luis Ibanez]

Hi,

To give an idea of how the documentation could be handled
on LaTeX using LyX, we have made available an illustration 
of the contents that Will proposed, at:

  http://www.cs.unc.edu/~ibanez/Insight/Documentation.tgz

which is expanded in 

  http://www.cs.unc.edu/~ibanez/Insight/Documentation

At the top level we have the bibliography files

  InsightToolkit.bib    // references in BibTex.
  InsightToolkit.bst    // Style for citation.

This bibliography files can be shared by all the books in 
the documentation.

Then one subdirectory per Book. For example the 
  'UsersGuide' subdirectory.

The subdirectory contains a UsersGuide.lyx file
that only put together the different Chapters by 
using "includes". In this way, each chapter is stored
in an independent file, in order to facilitate edition
and version control.

Chapters are in files Chapter1.lyx, Chapter2.lyx...

LyX can generate LaTeX code from the *.lyx files.
It is not desirable to edit the *.tex files, instead, 
latex code can be inserted directly in the original 
lyx files.

Other latex files that have been written without lyx
can be converted to LyX format, or even just 'included'
in lyx files.

These .tex files generated from lyx are compiled in the 
traditional way to generate a .dvi file and then a 
postscript file

   UsersGuide.ps

http://www.cs.unc.edu/~ibanez/Insight/Documentation/UsersGuide/UsersGuide.ps


   then using ps2pdf the UsersGuide.pdf file is generated


http://www.cs.unc.edu/~ibanez/Insight/Documentation/UsersGuide/UsersGuide.pdf


and finally, using the command in MakeHTML file , the latex code
is translated to HTML using latex2html.

The command used here was:  latex2html -html_version 4.0,math

(the 'math' option prevents equations from being translated 
into gif files)

The resulting HTML version of the original LyX files can be found at

http://www.cs.unc.edu/~ibanez/Insight/Documentation/UsersGuide/UsersGuide/index.html


An example of an equation can be found at the "Segmentation" chapter:


http://www.cs.unc.edu/~ibanez/Insight/Documentation/UsersGuide/UsersGuide/node34.html


-----------------

As Will, noted, the biggest problem for using LyX is the 
installation. Specially the required X Server for Windows.

It is interesting to note that LaTeX don't have to be installed
in order to use LyX for edition. That means that you can take
a .lyx file, edit it and send it back to the repository without
needing to 'compile' it.  

But if you want to produce the resulting postscript files from
a lyx file, a working installation of latex will be needed.

This is in some way what we are doing now with doxygen. Just 
editing sources and submiting them to the repository.





Luis