Re: Generating documentation from source code

[Paul E. Johnson]

"Marcus G. Daniels" wrote:
> 
> >>>>> "XH" == xueyue  <address@hidden> writes:
> 
> XH> there are too many supporting packages needed to
> XH> be installed by each user when he wants to configurate
> XH> swarmdoc-1.4, I am wandering if there is a version that has put
> XH> all these required supporting packages such into one.
> 
> All the tools that are needed are prebuilt for Windows on the Swarm
> 1.4.1 CD-ROM (the source code is there too).  The weak link with this
> environment is that TeX is very slow; however, the RTF targets should
> be reasonably efficient to use.
> 
> I don't know if a set of .deb/.rpm files exist to do the job
> correctly.  I suspect that most of this work has been done, but that
> tweaking is needed.  Paul?
> 
I wonder if this whole thread is not just a giant misunderstanding. If a
person wants to have the swarmdocs, there are precompiled versions
available at SFI.  Unless you are really wanting to become knowledgable
about SGML and docbook, that's what you ought to use.  You are just
begging for a giant hassle if you try to make swarmdocs from the source
and you are not already an expert.

Once or twice, I've accidentally downloaded the source for the swarmdocs
from the ftp site, when I actually intended to get the html or ps
versions. I imagine other people might make the same mistake, and from
looking at the source a person thinks they are intended to compile the
docs.  But that's such a huge job I can't believe anybody would rightly
take it on unless they really had to learn docbook/sgml for some other
reason.

If you do want to compile the swarmdocs on a Linux system, and I have no
idea why you want to do that, you are in for a lot of work.  As I
recall, these were the most significant issues I encountered.
  1. The pnmtopng converter program supplied by Redhat does not work. It
is a mystery to me why they still ship it out, the pngtools they
distribute don't even compile against the libraries they provide in
their distribution.  I've got executables for people to use.
  2. Redhat users need to remove the SGML-TOOLs collection redhat ships
out, since that is a Linux-doc version of SGML, not what we need. There
are RPMS for JADE, JADETEX, and the like, on the Cygnus webpage.  These
are not guaranteed to be up to date, but you can look at their srpms and
see what they do to get an idea of what needs to be done.  Here is a
link
   ftp://ftp.cygnus.com/pub/home/rosalia
Jade is the preferred set of programs that can do the sgml to html, tex,
or ps conversion.  It is a whole different beast than the sgml utilities
distributed with Redhat.  There is a fairly decent Jade/docbook site,
but I keep finding broken links or little undocumented bits.
  3. Alex L and I discovered that the version of the docbook dtd
distributed in the RPM format had been torqued beyond recognition in the
first lines and as a result that had to be replaced.  It turns out that
installing docbook dtd is not demanding, you just untar them and that's
it. But you have to be careful to tell swarmdocs where to find the dtd
in the configure statement.
  4. There is a problem with the iso-entity files. In Redhat/linux, they
have one naming convention, but there is a different naming convention
used in some parts of JADE (and possibly the swarm docs themselves), and
so you either have to rename a bunch of stuff in the SGML configuration
or just get a set of the iso files with the correct names.  I've got a
copy of them somewhere, I could look back and see what is necessary. Its
a stupid little problem, but was hard to find.  Something like the same
files are all renamed, appearing in Redhat's Linux-doc setup as ISOamsc
(and so forth) while in Swarmdocs are looking for files that appear as
iso-amsc.gml (and so forth for many files)
   5. I've never gotten the TEX version of the swarmdocs to compile
under linux.  At one time I had the problem pinned down and Marcus sent
me an example of a configuration file that worked on Solaris.  That
crossed my plate at the end of a long week fighting with it and I was
taking a trip and I never got back to it.  I can compile the HTML
version of swarmdocs and the swarmguide (under development,yes, I know,
its late).

In summary, if you already know docbook and have a bit of time and lots
of patience, you too can compile the swarmdocs.

On the other hand, why not just use the sets they already compiled at
SFI and save yourself the trouble.

Furthermore, if you do setup a system to compile the swarmdocs and think
it is easy to do, please jot down how you went about it because I'm
keeping a TODO list and you will be qualified to take care of many items
:)

-- 
Paul E. Johnson                         email: address@hidden
Dept. of Political Science              http://lark.cc.ukans.edu/~pauljohn
University of Kansas                    Office: (785) 864-9086
Lawrence, Kansas 66045                  FAX: (785) 864-5700

                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.