|
|
[Download
yads-0.93-beta.tar.gz]
Yads is a program that translates sets of XML documents
into a cohesive Web, or into a decent LaTeX document.
Twostones.org is generated by it. It has several cool
features, like the ability to embed Python or Perl in
your documents, a very powerful linking mechanism, or
the ability to deal with versions of a page in several
languages. It can output the documents, or a Perl
program that generates the document, which is very
useful to write CGI scripts.
Yads is written in Perl. It was written around 1999,
and even though I haven't touched its code since 2001 I
still use it regularly. It's not finished. There are
several things that should improve, and some that are
plain broken (like the attempt to write DTDs for your
documents).
One day I might get into it again. Maybe. The code is
reasonably readable, but there are so many things I
would do different today that it doesn't feel mine. (If
I ever get to it again the first thing I will do is to
make all the function calls using named parameters.)
I did made a timid
attempt at documentation, but Yads is not easy to
understand, nor it is well documented. Some people have
used it successfully to write embedded documentation of
complex software systems (I am among them; Yads can
extract XML from comments in source files of programs
written in several languages, and build a decent
documentation out of that). But it might very well be
that I will end up being its only user. Oh well.
| Do I Care About Yads? |
|
You do, if you
- Work with Linux or Unix.
- Maintain or have to build a medium size web
site (say, more than a couple documents and less
than a thousand), or have to document the source
code of a project that includes C/C++ and
Python/Perl.
- Textual content in plain HTML is a significant
part of your site.
- You don't want to spend your time re-writing
HTML files when the structure of the web or its
design changes.
- You want humans to edit/add to the content,
editing files that are reasonably easy to
understand (ie, XML). (if this is not a
requirement, and you don't mind programming Perl,
and your web is big, you are probably better off
generating the HTML online from a database.)
- You have enough time and stamina to go over
the learning curve.
|
| What Yads Has To Offer |
|
Once things are set up and you understand how Yads
works, maintaining a web site with it is trivial. You
can add/eliminate files and Yads will rebuild your
site with an updated map and new navigational aids and
everything will look just right, or you can change the
design of your entire web by editing just one file.
|
| What Has Been Done With Yads |
|
TwoStones.org,
the web site you are looking at, is entirely built by
yads. Whenever I have to add a new file I just copy
it in the right place, type a command (make), and the
new html tarball is ready to be uploaded to my ISP's
server.
Yads is being used in my R&D lab to build an
automatically generated/maintained web site, to which
~50 persons contribute in the form of XML files and
stuff for download. This site contains today 1392
(and growing) distinct files managed by Yads, 194 of
which are HTML files generated by Yads and strongly
inter-linked among themselves.
|
| Changes Since 0.6 |
|
- Added support for CGI's in Python.
- Dynamic documents (Perl and Python)- solved
bug that made it misplace the output of code
chunks in nested XML elements.
- PythonDoc looks for Python in /usr/local/bin
- Added mail attribute to author.
|
| Bugs |
|
- fref only works in root directory. If
in a subdirectory, the file won't be available for
download.
- Generation of DTDs does not work.
|
| Acknowledgements |
|
Ekkehard Kraemer (Ekkehard.Kraemer at t-systems.de)
and Hans Hoellt (Hans.Hoellt at t-systems.de) have
contributed suggestions, bug reports, and bug fixes.
|
|
|
Yads (Yads Advanced Documentation System)
is a XML-based system for building structured multi-node
documents. Output is HTML or LaTeX.
|
