On Aug 18, 2008, at 4:45 PM, Gustavo Gutierrez wrote:
Although Denys says that ozdoc is easy to use for own
documentation files, it appears this is not the case with the
Mozart documentation itself. For example, it seems it requires an
nsgmls installation. Has anyone an idea how to render (parts of)
the Mozart documentation without "any frills" (e.g., only HTML)?
To generate documentation is just a nightmare before every mozart
release. I think we should explore other ways to generate
documentation in html, pdf and maybe chm (windows) formats. The
point here is to see what we need from a documentation generating
system:
1) To parse sgml or xml as input formats. In this way changes won't
be (hopefully) so huge. Currently nsgmls is used for this.
2) Render latex formulas which are embedded in the document with a
special tag.
3) To highlight oz syntax (most of the examples). Currently emacs
is used for this.
Any suggestion is welcome on the topic. I think the time spent in
setting up a system (all the packages with right the corresponding
versions) to be able to generate the documentation increases from
time to time and having something standard and recent might save
time in the future. For instance, we should take a look at DocBook.
Are you suggesting writing a new transformation of the Oz
Documentation format into some more standard format (like DocBook)?
One may even consider doing this transformation only once and then
doing all further edits in the new format.
The BNF of the Oz doc format is relatively small, but the doc files
define their own extension of this format, so I don't know how easy
such a transformation actually is.
3) To highlight oz syntax (most of the examples). Currently emacs
is used for this.
Just to mention: for the Oz syntax highlighting in the HTML
documentation of my software Strasheela I use htmlize.el (http://
www.emacswiki.org/cgi-bin/wiki/Htmlize). It was more easy for me to
set up than understanding the Mozart way of doing it. There is also
SaveAsHtml (http://www.emacswiki.org/cgi-bin/wiki/SaveAsHtml).
Still, these Emacs-based translators are also not exactly anything
"standard". Also, they only output HTML, no Latex (PS, PDF).
Best
Torsten
--
Torsten Anders
Interdisciplinary Centre for Computer Music Research
University of Plymouth
Office: +44-1752-586219
Private: +44-1752-558917
http://strasheela.sourceforge.net
http://www.torsten-anders.de
_________________________________________________________________________________
mozart-users mailing list
[email protected]
http://www.mozart-oz.org/mailman/listinfo/mozart-users
