>>Date: Wed, 15 Nov 2000 10:31:52 +0100
>>From: "Idar Tollefsen" <[EMAIL PROTECTED]>
>>To: <[EMAIL PROTECTED]>
>>Subject: Documenting software
>>
>>Hello,
>>
>>As some of you might know, documentation is not the highest priority in many
>>software projects. My new workplace is no exception. I therefore want to try
and
>>set a standard here for how documentation is supposed to be done.
>>
>>We use WinNT, and I'm therefore using LyX for Win32 (1.1.5fix2). I have
>>an initial question about this environment: If I want to introduce LyX to
these
>>people, it is important that I can get it running with a, preferably, free
X-Server,
>>or at least a low cost one. Could anyone recommend one? I am personaly using
>>ReflectionX from WRQ, and I'm _very_ happy with it, but it costs too much.
>>
>>But my real question what type of document to use?
>>
>>I have written one user's manual using the Book class. These seem to work
>>well, but I would like som input from others who have uses LyX or LaTeX to
>>document software.
>>
>>I need both to document the code and write manuals for the users. We need
>>conversion to PDF (no problem) and to PS for printing (also no problem). We
also
>>require conversion to HTML to be able to publish our documentation on our
>>Intranett (this place has over 7000 employees, and some of our systems has
>>about 2000 users). I am now in the process of trying to install ans use
>>LaTeX2HTML, which I hope will do the trick.
>>
>>If possible, conversion to "help" formats would be great. Does anyone know of
>>a LaTeX to WinHelp or HTML Help converter? If I get LaTeX2HTML to work,
>>we could possibly assemble the HTML Help files ourselves, but it would be
>>great to get them ready made.
>>
>>Any hints and tips would be greatly appreciated.
>>
>>
>>- IT
>>
>>
My usual solution to intranet access to documents:
- write it in LateX or easy-to-turn in LaTeX tool (obviously Lyx does it)
- turn it in HTML with maximum split-up (i.e. one file per sheet of the
logical tree in the TOC)
- index it to give direct access to elementary pages upon a search equation.
Quite easy to set up, but the query part is more difficult
to popularize, du to the fact that it needs a understanding
of of the basic query mechanism properties.
Answers to queries feeds back HTML pages so that you can interlace
query navigation with hypertext navigation.
Of course you may hack the building procedure to include particular
features (e.g. make all images thumbnails by default with hyperlink on
full image). LaTeX2HTML can be paraemtrized to a really complex level, and
allows to insert hypertextual instructions ignored by the TeX typography
(which remains available from the LaTeX or LyX source).
Obviouly also, the query page can explore one or more
docs (even distributed in the Intranet) upon checkbox selection.
I used this on Lyx doc to provide the indexed access in parallel
with the acees from inside LyX; it fails only on constructs
of the LyX docs which are intended to show the result in LyX itself
(mathed mostly) but remains usable.
--
Jean-Pierre
