<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<META content="MSHTML 6.00.2800.1264" name=GENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY>
<DIV><FONT face=Arial size=2>Sorry, Tom. Of course, it is not a bad idea, and it
is only a _disk space_ issue.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>But remember, that 99% of all users do not need
your xml, dtd etc - they need plain text on the screen, so pdf file or html file
looks quite</FONT></DIV>
<DIV><FONT face=Arial size=2>enough for the _binary_ distribution. Anyway, it's
not important, I have not any objections.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>Doxigen (JavaDoc etc) is quite another issue.
In real projects, it is not _redundant_. Reason is very
simple:</FONT></DIV>
<DIV><FONT face=Arial size=2>- documentation is edited and corrected by
_technical editor_, _technical corrector_ etc;</FONT></DIV>
<DIV><FONT face=Arial size=2>- you do not want them to edit a
sources;</FONT></DIV>
<DIV><FONT face=Arial size=2>- you do not want to have a include file, having
90% of the documentation and 10% of the source code.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>But, on the other hand, you want to write
documentation in such style, that it is auto-referenced - if I write out API
call, I'd like to see html link on this place, not a plain
text.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>As a result, after a few experiments, we added
special suffix, .dxf, to the list of source files, and moved all _BIG_ pieces of
documentation into it. For example, if we have some subsystem, we put subsystem
description, with a simple usage example, here, and enlist all API interfaces in
the end.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>Remember, that user is not looking for the 'CLASS'
or 'ABC::xxx' function; he is looking for, for example, 'How can I create,
maintain and delete a thread and set/unset mutex, when I use this
system'.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>It is very important. Documentation have a 3 file
types - </FONT></DIV>
<DIV><FONT face=Arial size=2>- plain html documents, used as a index-I
level;</FONT></DIV>
<DIV><FONT face=Arial size=2>- dxf files, working as an introduction to the
subsystems, servers, config files etc, and used as a index-II
level;</FONT></DIV>
<DIV><FONT face=Arial size=2>- .cpp and .h files, used to generate detailed
references to the api functions.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>It worked fine. I saw the same approach in a few
other projects (QT, for example) - do not say _I have a doxigen and it
provides a documentation_ (because it provides a garbage) but say _I have a
documentation, and I use doxigen to document functions and classes, so I am 100%
sure than they are documented up-to-date, and I use dxf files for other
documentation, so they are processed by technical editor and corrector, are
written in free-lance style, do not create a mess in include directories, and
uses doxigen class and method description for detailed references_.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>Just again - Doxigen or JavaDoc provides, by
themself, a mess of 90% useless reference manuals. </FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>Here is an example (I used abandoned project. btw -
EOL project is abandoned, but exists and in working conditions, if someone
is interested in multi-platform middleware, we can try to put life into
it).</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>Level I document - plain html:</FONT></DIV>
<DIV>
<HR>
</DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV>
<H1>Exigen Middleware: Exigen Object Library (EOL) Documentation </H1><B><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/EOL_CHANGES.html">Release
Notes.</A></B> <BR>
<HR width="100%">
<H2>1. Quick Start</H2>
<DL>
<DD><B><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/eol/eol_intro.html">Introduction
and functional overview</A></B>
<DD><B><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/SECURITY.html">EOL
Security design</A></B>
<DD><B>EOL Cookbook</B>
<UL>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__CHAT__EXAMPLE.html">Sample
Chat Application: Introduction</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__CLIENT__MAP.html">Client
EODL mapping and implementation</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__SERVER__MAP.html">Server
EODL mapping and implementation</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__OBJ__LIFE.html">Object
Lifecycle Usage</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__EVOLV__DESIGN.html">Creating
evolving designs: multiple versions of the simple chat application</A>
</LI></UL></DD></DL><BR>
<HR width="100%">
<H2>2. EOL User's Guide</H2>
<UL>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__ENS__USER.html">EOL
Naming Service User's Guide</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/DA_USER.html">Dynamic
type usage</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/EIO_Guide.html">EIO
Introduction and MT Guide</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__ELS__USER.html">ELS
User's Guide</A>
<LI><A
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/group__ETP__USER.html">ETP
User's Guide</A> </LI></UL></DIV>
<DIV><FONT face=Arial size=2></FONT><FONT face=Arial size=2>
<HR>
</FONT></DIV>
<DIV><FONT face=Arial size=2>Level 2 document - .dxf file.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV>
<CENTER><A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/index.html">Main
Page</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/modules.html">Modules</A>
<A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/namespaces.html">Namespace
List</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/hierarchy.html">Class
Hierarchy</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/classes.html">Alphabetical
List</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/annotated.html">Compound
List</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/files.html">File
List</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/namespacemembers.html">Namespace
Members</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/functions.html">Compound
Members</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/globals.html">File
Members</A> <A class=qindex
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/pages.html">Related
Pages</A> </CENTER>
<HR>
<H1>EOL Naming Service : User's Guide</H1>
<TABLE cellSpacing=0 cellPadding=0 border=0>
<TBODY></TBODY></TABLE>
<H2>Introduction</H2>
<P>EOL Objects can be of two types:
<P>
<UL>
<LI><B>well known</B> - with well known object references which can be written
out before object is running;
<LI><B>normal</B> - which contains signature based on the random seed and must
be registered <EM>before</EM> any client can subscribe to them. </LI></UL>Naming
service provides:
<P>
<UL>
<LI>registration (named <B>'binding'</B>) of the server objects;
<LI>resolution of the objects by their names;
<LI>basic access control;
<LI>basic redundancy for the objects. </LI></UL>
<H2>EOL Naming Service API</H2>
<P>Usually programs should not bother about naming service and work with <B>Name
Service</B> directly, but should use <B>EOL Naming Service API</B> instead. This
API allows:
<P>
<UL>
<LI>Register server object by its name (<A class=el
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/classEOLServerObject.html#a26">EOLServerObject::makeBinding</A>())
for the full or restricted access. Server object can be registered a few times
with the different names and different access rights, and can be unregistered
as well. A few servers can register objects with the same names that allows to
set up redundant configurations.
<P></P>
<LI>Subscribe to the object by its name (in synchronous or asynchronous mode).
If a few servers were registered, subscription will choose the nearest server
and skip servers that do not answer.
<P></P>
<LI>Use <A class=el
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/classENSNameContext.html">ENSNameContext</A>,
<A class=el
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/classEOLStaticNameContext.html">EOLStaticNameContext</A>,
<A class=el
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/classEOLResolver.html">EOLResolver</A>
and <A class=el
href="http://amazon.exigengroup.com/mware/build.eol/doc/build.doxy/html/classEOLBinding.html">EOLBinding</A>
classes for more specific tasks. </LI></UL></DIV>
<DIV><FONT face=Arial size=2>
<HR>
</FONT></DIV>
<DIV><FONT face=Arial size=2>=================</FONT></DIV>
<DIV><FONT face=Arial size=2><snip><BR><BR>Geez O'pete !!!! You are
killing me.<BR><BR>XML is easily extensible to almost any other format with a
standard DTD. AND <BR>can be utilized and referenced with readbility
formulas(Dale-Chall, Flesch) <BR>so that even general user documentation can be
compiled very quickly.<BR><BR>i.e. KDE document sourcing, etc.....<BR><BR>As for
LaTeX ----- is very easy to transform this format to desktop reference
<BR>materials, for various different platforms. Given that Osiris is not system
<BR>dependant; this makes very good sense.<BR><BR>BTW --- doxygen "only" files
are redundant. It would be considerably easier to <BR>just correctly format the
comments directly into the sources. Why comment <BR>source code to make it
incompatible with doxygen, then make another file for <BR>the same data that is
compiled by said document.<BR><BR>-----BEGIN PGP SIGNATURE-----<BR>Version:
GnuPG v1.2.2
(GNU/Linux)<BR><BR>iD8DBQFAOHBZQT2komo99ukRAmNdAKCM7VkhSvrBNkI+/E7MZtq2YTY08ACgvwYI<BR>9XDt+0aaIZr/keNomxrnrqg=<BR>=dMhp<BR>-----END
PGP
SIGNATURE-----<BR><BR>_______________________________________________<BR>osiris-devel
mailing list<BR></FONT><A href="mailto:osiris-devel@lists.shmoo.com"><FONT
face=Arial size=2>osiris-devel@lists.shmoo.com</FONT></A><BR><A
href="https://lists.shmoo.com/mailman/listinfo/osiris-devel"><FONT face=Arial
size=2>https://lists.shmoo.com/mailman/listinfo/osiris-devel</FONT></A><BR></DIV></BODY></HTML>