--- Begin Message ---
[ Tess - I'm not on the PyOGP list to post this response - can you do
it for me? ]
The OGP documentation needs to be in the form of a concise, formal,
technical standard. The needs for such a document are a bit different
than for API or system documentation in general.
I looked at quite a number of documentation systems before settling on
W3C's "XML Specification 2.10", used for many W3C standards. It has
been used extensively by others, has a base of useful tools (XSLT into
HTML and PDF), and has a schema descriptive enough to do real lists
and tables, without being an overbearing taxonomy of publishing forms
(like, say, DocBook)
The main page is here:
http://www.w3.org/2002/xmlspec/
The guide is here, though it is out-of-date, referencing version 2.1:
http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm
We use a limited subset of that schema (details on request). This
subset is what we then transform (via XSLT) into HTML, PDF and
WikiText. I intend, as we get closer to IETF draft submission, to
XSLT transform it into RFC2629 as well, so then we can produce the
required text format of internet drafts.
There is also http://xml.resource.org/ which converts documents
written a la http://www.faqs.org/rfcs/rfc2629.html
I have worked with the RFC2629 XML format in the past. It is still
the only sane way to produce IETF drafts. However, it is a pretty low-
feature schema and didn't seem to have enough for our purposes.
Further, the available tools for it are limited (and written in TCL).
What would be cool for commenting would be something like the
Djangobook does though:
http://www.djangobook.com/about/comments/
This reminds me of:
http://www.co-ment.net/
Which isn't as pretty as the Django Book project, but *IS* open
source. And, oddly, is built on Django!
- Zero Linden
Mark Lentczner
Engineering Director
API & Architecture
Linden Lab
[EMAIL PROTECTED]
Zero Linden
[EMAIL PROTECTED]
--- End Message ---
_______________________________________________
Click here to unsubscribe or manage your list subscription:
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp
