[Insight-developers] Ideas for online documentation

[Sayan Pathak]

Hello,
This the SGI website for their STL stuff
http://www.sgi.com/Technology/STL/


Couple of things that are missing: no use of intricate equations and also no
pictures.

Vikram, found out that these pages were directly written in HTML and not
generated using any conversion tools.

I think we need to have a clear roadmap regarding the documentation we want
to generate for the whole toolkit. Once we have that list we could decide
one by one, who will be responsible for it and what editor will be used.

Someone please correct me if I am wrong, one thing I got today from the
discussion was:
 For getting an high level class design review one could use any form of
editing tool that gets the message across.

Rest of the documentation issues are left for further discussion.


Thanks, Wishing every one a happy new year,
Sayan

-----Original Message-----
From: insight-developers-admin@public.kitware.com
[mailto:insight-developers-admin@public.kitware.com]On Behalf Of Luis
Ibanez
Sent: Thursday, December 28, 2000 7:59 PM
To: Will Schroeder
Cc: insight-developers@public.kitware.com
Subject: [Insight-developers] Documentation: LaTeX, LyX and HTML



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.pd
f


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/in
dex.html


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


http://www.cs.unc.edu/~ibanez/Insight/Documentation/UsersGuide/UsersGuide/no
de34.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




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