[Swift-devel] Re: Notes on maintaining the swift web and docs

[David Kelly]

Hello all,

I have been trying to generate the Swift docs with docbook, but am having
only partial success. If anyone happens to be familiar with this process,
any help would be appreciated.

I have read the README and wiki link that Michael sent, but there are still
a few issues. Here is an overview of everything I have done thus far:

After making some changes to the documentation, I created a symlink to
docbooks.
I have formatting/docbooks pointing to /home/hategan/docbook/docbook-xsl.
I have tried all of the other docbook directories mentioned in the readme
and wiki, but they all seem to behave the same
Next when I attempted to run buildguides.sh I got an error message that
fop/fop.sh was not found.
I found /home/hategan/fop.tar.gz and uncompressed it into the doc directory.
That got rid of the fop errors, but then I received "Error: JAVA_HOME is not
defined correctly"
Then I followed a maze of symlinks to what I believe is the correct
JAVA_HOME on this system (login.ci.uchicago.edu) at
/usr/lib/jvm/jre-1.4.2-gcj
Then I received the following errors:

[INFO] Using org.apache.xerces.parsers.SAXParser as SAX2 Parser
[Fatal Error] refentry.xsl:314:58: The string "--" is not permitted within
comments.
[ERROR] javax.xml.transform.TransformerConfigurationException:
javax.xml.transform.TransformerException: org.xml.sax.SAXParseException: The
string "--" is not permitted within comments.
make: *** [userguide.pdf] Error 2

I tracked refentry.xsl down and found it in
/usr/share/apps/ksgmltools2/docbook/xsl/html/refentry.xsl.
I could try to modify the comments but I do not have permission. The error
is preventing pdf files from being created.

After this section fails, it moves to create the PHP files. The PHP files
get created, and works for the most part except for one nagging problem.
Next to each section number (1.1, 1.2, etc) a diamond with a question mark
inside of it appears.
I double checked that they do not exist in the xml file, only the php file
I think this is some strange character map issue. The PHP file sets the
character set to UTF-8. When I change firefox to render the page in
ISO8859-15 it works fine.
I have tried changing the character set of the php file, and also tried
setting the character set through .htaccess with no luck (the pages are
being served out of my public_html directory for testing)

Any other ideas and suggestions would be appreciated.

Thanks!

Regards,
David


Message: 2
> Date: Tue, 25 May 2010 19:18:57 -0500 (CDT)
> From: Michael Wilde <wilde at mcs.anl.gov>
> Subject: [Swift-devel] Notes on maintaining the swift web and docs
> To: Swift Devel <swift-devel at ci.uchicago.edu>
> Message-ID: <5124436.99271274833137828.
> JavaMail.root at zimbra>
> Content-Type: text/plain; charset=utf-8
>
> To help David in creating a procedure for test copies of the Swift web and
> for generating the Swift docs with docbook, I placed notes gleaned from
> swift-devel at:
>
>  http://www.ci.uchicago.edu/wiki/bin/view/SWFT/MaintainingSwiftWebContent
>
> If anyone has tips to refine those instructions, please update that page or
> post suggestions here for David to try and then post for general use.
>
> As suggested on that page, most of the notes should wind up in README files
> at www/ and docs/
>
> - Mike
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20100527/43b0387e/attachment.html>