[Casa-framework] another svn query

Sat Oct 28 15:47:34 EDT 2006

Hi Kumar,

This was discussed in a series of messages from June 2004 that are in the 
aips2-developers mailing list. I have attached the messages I still have 
in my mailbox regarding doxygen.  The last one includes a script based on 
something Ger did as well as a cxx2html tag mapping and a "finalized" 
change proposal.

Raymond

On Sat, 28 Oct 2006, Kumar Golap wrote:

> I don't know much about the doxygen markup syntax or doxygen
> switches...but is it going to be difficult to write a script that
> convert  the cxx2html tags to doxygen tags.
> 
> Kumar
> 
> On 10/28/06, Raymond Rusk <Raymond.Rusk at nrc-cnrc.gc.ca> wrote:
> > On Sat, 28 Oct 2006, Wim.Brouw at csiro.au wrote:
> >
> > >
> > > Raymond,
> > >
> > > Ger produced a full tree of aips++ in early 2002, by just adding a
> > > script to a doxygen run.
> >
> > Hi Wim,
> >
> > I think that I have roughly the same thing for the latest framework code
> > at http://shiraz.drao.nrc.ca:8080/casadoc/.  Doxygen has quite a few
> > switches but I probably have the most important ones toggled correctly in
> > the configuration file.  The main page looks like the ATM doxygen output
> > because it is the only code that has doxygen markup.  However, links to
> > everything else are at the top of the page.
> >
> > Raymond
> >
> > > It created a full tree etc. Your address is part of that, see:
> > > http://www.astron.nl/~gvd/aips++/docxxhtml/index.html
> > >
> > > For the full story (as of that date).
> > >
> > > Wim
> > >
> > >
> > >
> > > ------------------------------------------------------------------
> > > Contact details: www.astro.rug.nl/~brouw/wbrouw.html
> > > ------------------------------------------------------------------
> > >
> > >
> > >
> > > > -----Original Message-----
> > > > From: casa-framework-bounces at donar.cv.nrao.edu
> > > > [mailto:casa-framework-bounces at donar.cv.nrao.edu] On Behalf
> > > > Of Raymond Rusk
> > > > Sent: 27 October 2006 22:49
> > > > To: jaeger at cpsc.ucalgary.ca
> > > > Cc: casa-framework at nrao.edu
> > > > Subject: Re: [Casa-framework] another svn query
> > > >
> > > > Hi Shannon,
> > > >
> > > > ASTRON is further along with Doxygen than we are.  If you go
> > > > to
> > > > http://www.astron.nl/~gvd/aips++/docxxhtml/classQuantumHolder.
> > > > html, for instance, you get a nice class hierarchy diagram.
> > > > It is the non-framework
> > > > AIPS++, of course, but the basic libraries haven't changed
> > > > that much.
> > > > AIPS++It
> > > > will be nice when we have this level of documentation as well.
> > > >
> > > > Raymond
> > > >
> > > > On Fri, 27 Oct 2006, jaeger at cpsc.ucalgary.ca wrote:
> > > >
> > > > > au contraire!
> > > > >
> > > > > Doxygen provides a much richer document set the latex
> > > > generated from
> > > > > the xml, from what I can see.  At least from a programmers point of
> > > > > vies.
> > > > >
> > > > > Based on what I've seen the xml generated documentation is
> > > > a lot like
> > > > > reading a book, not really a website.  There are also a lot of
> > > > > comments there that are more about how to use casapy then about the
> > > > > software design.  In fact there is very little to no
> > > > information about
> > > > > software design.
> > > > >
> > > > > Doxygen produces a hierarchical set of webpages that even includes
> > > > > class hierarchy diagrams.  A much more useful tool to the developer
> > > > > then stripping out the software design stuff in amongst the
> > > > software
> > > > > usage stuff.
> > > > >
> > > > > Shannon
> > > > >
> > > > > > Documentation should be in the XML, the headers are generated.
> > > > > > Doxygen on generated headers makes little sense, it could be done
> > > > > > though if there is demand, just not right now.
> > > > > >
> > > > > > wes
> > > > > > wyoung at aoc.nrao.edu
> > > > > >
> > > > > >
> > > > > > On 27 Oct 2006, at 17:06, Raymond Rusk wrote:
> > > > > >
> > > > > > > Hi Wes/David,
> > > > > > >
> > > > > > > Chiming in on David's comment about preserving programmer's
> > > > > > > statement of intent from the past, one issue I see with our
> > > > > > > auto-generated headers is that it makes in-line
> > > > documentation more
> > > > > > > of a challenge.  Much of the documentation in the old
> > > > DOs appears
> > > > > > > in the headers.  That is where Doxygen markup would normally
> > > > > > > appear. Our new framework makes it easier to lose this
> > > > information
> > > > > > > than to retain it.
> > > > > > >
> > > > > > > Raymond
> > > > > > >
> > > > > > > On Fri, 27 Oct 2006, Wes Young wrote:
> > > > > > >
> > > > > > > > In a word, no.  It's a clean break.  Yes we could have but we
> > > > > > > > chose to leave the past behind. So you want cvs history
> > > > use cvs commands.
> > > > > > > >
> > > > > > > > wes
> > > > > > > > wyoung at aoc.nrao.edu
> > > > > > > >
> > > > > > > >
> > > > > > > > On 27 Oct 2006, at 16:11, David King wrote:
> > > > > > > >
> > > > > > > > > Hi all:
> > > > > > > > >
> > > > > > > > > One thing I'd wanted to ask:  what about retaining the
> > > > revision
> > > > > > > > > history from cvs?  My perusal of the svn doc seemed to
> > > > indicate
> > > > > > > > > they considered it valuable (I agree), and I think they worked
> > > > > > > > > hard to allow it to be preserved on import from cvs,
> > > > but I dont
> > > > > > > > > see it in the svn repository.  (Is it already too late)?
> > > > > > > > >
> > > > > > > > > dk
> > > > > > > >
> > > > > >>> _______________________________________________
> > > > > > > > Casa-framework mailing list
> > > > > > > > Casa-framework at donar.cv.nrao.edu
> > > > > > > > http://listmgr.cv.nrao.edu/mailman/listinfo/casa-framework
> > > > > > > >
> > > > > > >
> > > > > > > --
> > > > > > > Dr. Raymond Rusk
> > > > Dr. Raymond
> > > > > > > Rusk
> > > > > > > ALMA Software Engineer
> > > > Ingenieur Logiciel
> > > > > > > ALMA
> > > > > > > National Research Council Canada   Conseil national de recherches
> > > > > > > Canada
> > > > > > > Herzberg Institute of Astrophysics   L'Institut Herzberg
> > > > > > > d'Astrophysique
> > > > > > > DRAO, P.O. Box 248                                    OFRA, B.P.
> > > > > > > Box 248
> > > > > > > Penticton, BC V2A 6J9           |\^/|         Penticton, (C.-B.)
> > > > > > > V2A 6J9
> > > > > > > Government of Canada         _|\|   |/|_          Gouvernement du
> > > > > > > Canada
> > > > > > > Tel: (250)490-4347           >         <              Tel: (250)
> > > > > > > 490-4347
> > > > > > > Fax: (250)493-7767            >_./|\._<               Fax: (250)
> > > > > > > 493-7767
> > > > > > > Raymond.Rusk at nrc-cnrc.gc.ca                  Raymond.Rusk at nrc-
> > > > > > > cnrc.gc.ca
> > > > > >
> > > > > > _______________________________________________
> > > > > > Casa-framework mailing list
> > > > > > Casa-framework at donar.cv.nrao.edu
> > > > > > http://listmgr.cv.nrao.edu/mailman/listinfo/casa-framework
> > > > > >
> > > > >
> > > > >
> > > >
> > > > --
> > > > Dr. Raymond Rusk                                        Dr.
> > > > Raymond Rusk
> > > > ALMA Software Engineer                           Ingenieur
> > > > Logiciel ALMA
> > > > National Research Council Canada   Conseil national de
> > > > recherches Canada
> > > > Herzberg Institute of Astrophysics   L'Institut Herzberg
> > > > d'Astrophysique
> > > > DRAO, P.O. Box 248                                    OFRA,
> > > > B.P. Box 248
> > > > Penticton, BC V2A 6J9           |\^/|         Penticton,
> > > > (C.-B.) V2A 6J9
> > > > Government of Canada         _|\|   |/|_
> > > > Gouvernement du Canada
> > > > Tel: (250)490-4347           >         <              Tel:
> > > > (250)490-4347
> > > > Fax: (250)493-7767            >_./|\._<               Fax:
> > > > (250)493-7767
> > > > Raymond.Rusk at nrc-cnrc.gc.ca
> > > > Raymond.Rusk at nrc-cnrc.gc.ca
> > > > _______________________________________________
> > > > Casa-framework mailing list
> > > > Casa-framework at donar.cv.nrao.edu
> > > > http://listmgr.cv.nrao.edu/mailman/listinfo/casa-framework
> > > >
> > >
> >
> > --
> > Dr. Raymond Rusk                                        Dr. Raymond Rusk
> > ALMA Software Engineer                           Ingenieur Logiciel ALMA
> > National Research Council Canada   Conseil national de recherches Canada
> > Herzberg Institute of Astrophysics   L'Institut Herzberg d'Astrophysique
> > DRAO, P.O. Box 248                                    OFRA, B.P. Box 248
> > Penticton, BC V2A 6J9           |\^/|         Penticton, (C.-B.) V2A 6J9
> > Government of Canada         _|\|   |/|_          Gouvernement du Canada
> > Tel: (250)490-4347           >         <              Tel: (250)490-4347
> > Fax: (250)493-7767            >_./|\._<               Fax: (250)493-7767
> > Raymond.Rusk at nrc-cnrc.gc.ca                  Raymond.Rusk at nrc-cnrc.gc.ca
> > _______________________________________________
> > Casa-framework mailing list
> > Casa-framework at donar.cv.nrao.edu
> > http://listmgr.cv.nrao.edu/mailman/listinfo/casa-framework
> >
> 

-- 
Dr. Raymond Rusk                                        Dr. Raymond Rusk
ALMA Software Engineer                           Ingenieur Logiciel ALMA
National Research Council Canada   Conseil national de recherches Canada
Herzberg Institute of Astrophysics   L'Institut Herzberg d'Astrophysique
DRAO, P.O. Box 248                                    OFRA, B.P. Box 248
Penticton, BC V2A 6J9           |\^/|         Penticton, (C.-B.) V2A 6J9
Government of Canada         _|\|   |/|_          Gouvernement du Canada
Tel: (250)490-4347           >         <              Tel: (250)490-4347
Fax: (250)493-7767            >_./|\._<               Fax: (250)493-7767
Raymond.Rusk at nrc-cnrc.gc.ca                  Raymond.Rusk at nrc-cnrc.gc.ca
-------------- next part --------------
From MAILER-DAEMON Sat Oct 28 12:40:40 2006
Date: 28 Oct 2006 12:40:40 -0700
From: Mail System Internal Data <MAILER-DAEMON at nrc-cnrc.gc.ca>
Subject: DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA
Message-ID: <1162064440 at nrc-cnrc.gc.ca>
X-IMAP: 1162064198 0000000016
Status: RO

This text is part of the internal format of your mail folder, and is not
a real message.  It is created automatically by the mail system software.
If deleted, important folder data will be lost, and it will be re-created
with the data reset to initial values.

From aips2-developers-admin at donar.cv.nrao.edu  Sat Jun 12 08:30:52 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5CFUpHB024027
	for <rrusk at localhost>; Sat, 12 Jun 2004 08:30:52 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Sat, 12 Jun 2004 08:30:52 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh2.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id MT4A1TR1; Sat, 12 Jun 2004 03:32:18 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5C7U1Sl000516;
	Sat, 12 Jun 2004 03:30:01 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5C7U1g16654;
	Sat, 12 Jun 2004 03:30:01 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5C7TXg16627
	for <aips2-developers at donar.cv.nrao.edu>; Sat, 12 Jun 2004 03:29:33 -0400
Received: from revere.aoc.nrao.edu (revere.aoc.nrao.edu [146.88.1.15])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5C7TXeL017913
	for <aips2-developers at nrao.edu>; Sat, 12 Jun 2004 03:29:33 -0400
Received: from cluster.aoc.nrao.edu (cluster [146.88.10.82])
	by revere.aoc.nrao.edu (8.11.6/8.11.6) with ESMTP id i5C7TTN30806
	for <aips2-developers at nrao.edu>; Sat, 12 Jun 2004 01:29:29 -0600
Received: from localhost (jmcmulli at localhost)
	by cluster.aoc.nrao.edu (8.12.8/8.12.8/Submit) with ESMTP id i5C7TT1F000878
	for <aips2-developers at nrao.edu>; Sat, 12 Jun 2004 01:29:29 -0600
Message-ID: <Pine.LNX.4.44.0406120128350.701-100000 at cluster>
From: Joe McMullin <jmcmulli at nrao.edu>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: aips2-developers at nrao.edu
Subject: [aips2-developers]Doxygen Change Proposal
Date: Sat, 12 Jun 2004 00:29:29 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-Authentication-Warning: cluster.aoc.nrao.edu: jmcmulli owned process doing -bs
X-BeenThere: cluster.aoc.nrao.edu: jmcmulli owned process doing -bs
X-Mailman-Version: cluster.aoc.nrao.edu: jmcmulli owned process doing -bs
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C4504F.64700EAD"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 1

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C4504F.64700EAD
Content-Type: text/plain;
	charset="iso-8859-1"

Title:				Switch code documentation to doxygen
Person responsible:		Joe McMullin (jmcmulli at nrao.edu)
Originator of proposal:		David DeBonis (ddebonis at nrao.edu)
Exploders targeted:		aips2-developers
Time table:
Date of issues:			2004 Jun 12
Comments due:			2004 Jun 18
Revised proposal:		2004 Jun 21
Final comments due:		2004 Jun 28
Decision date:			2004 Jul 1

Statement of goals:
----------------------------
Adopt doxygen as the standard AIPS++ code documentation engine.

Background:
------------------
Doxygen has become a widpread standard for documenting source code (for
a 
partial list of projects using doxygen see 
http://www.stack.nl/~dimitri/doxygen/projects.html).  Doxygen supports a

range of output formats (such as html, latex, man pages, rtf, xml, with
ps 
and pdf being indirectly supported through latex "make ps / pdf") and is

highly portable (Linux and Unix flavors, with executables for Windows,
and 
Mac OS X also available).

Given that we maintain (and are about the only users of) cxx2html it
would be 
better to now switch to doxygen.

As a prototype, I have doxygenated some the implement directory of aips
(see 
http://www.aoc.nrao.edu/~ddebonis/doxygen) with a script I made using
Ger's 
script as a translator.

Most of the mappings between cxx2html tags and doxygen tags have been
made 
through Ger's perl script which I have attached to this proposal.

Summary:
---------------
Switching to doxygen will remove an AIPS++ created tool (cxx2html) that
we 
maintain and replace it with a more standard code documentation tool.

Expected Impact:
--------------------------
Adoption of doxygen will require the translation of cxx2html tags to
doxygen 
tags.  Ger has written a script to do most of this already (a few
additional 
tags need to be added to the translator) and I have already created an
upper 
level script to drive the translator.

Changes will need to be put in place in the build system to replace
cxx2html 
with doxygen, pointers to obtaining doxygen will need to be put in the 
documentation as well as how we expect to use doxygen.  Also, a doxygen 
configuration file (which has already been created) will be added that 
defines how doxygen parses and presents the documentation.

Since this change will touch nearly every file, I believe that a code
freeze 
(of less than half a day) should occur once the scripts have been
refined and 
thoroughly tested.

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C4504F.64700EAD
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
charset=3Diso-8859-1">
<META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
5.5.2657.73">
<TITLE>[aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>
<BR>

<P><FONT SIZE=3D2>Title:&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Switch code documentation to =
doxygen</FONT>
<BR><FONT SIZE=3D2>Person responsible:&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Joe McMullin =
(jmcmulli at nrao.edu)</FONT>
<BR><FONT SIZE=3D2>Originator of proposal: =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; David DeBonis =
(ddebonis at nrao.edu)</FONT>
<BR><FONT SIZE=3D2>Exploders targeted:&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; aips2-developers</FONT>
<BR><FONT SIZE=3D2>Time table:</FONT>
<BR><FONT SIZE=3D2>Date of issues: =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2004 Jun 12</FONT>
<BR><FONT SIZE=3D2>Comments due:&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2004 Jun 18</FONT>
<BR><FONT SIZE=3D2>Revised =
proposal:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2004 Jun 21</FONT>
<BR><FONT SIZE=3D2>Final comments due:&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2004 Jun 28</FONT>
<BR><FONT SIZE=3D2>Decision date:&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2004 Jul 1</FONT>
</P>

<P><FONT SIZE=3D2>Statement of goals:</FONT>
<BR><FONT SIZE=3D2>----------------------------</FONT>
<BR><FONT SIZE=3D2>Adopt doxygen as the standard AIPS++ code =
documentation engine.</FONT>
</P>

<P><FONT SIZE=3D2>Background:</FONT>
<BR><FONT SIZE=3D2>------------------</FONT>
<BR><FONT SIZE=3D2>Doxygen has become a widpread standard for =
documenting source code (for a </FONT>
<BR><FONT SIZE=3D2>partial list of projects using doxygen see </FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://www.stack.nl/~dimitri/doxygen/projects.html" =
TARGET=3D"_blank">http://www.stack.nl/~dimitri/doxygen/projects.html</A>=
).&nbsp; Doxygen supports a </FONT>
<BR><FONT SIZE=3D2>range of output formats (such as html, latex, man =
pages, rtf, xml, with ps </FONT>
<BR><FONT SIZE=3D2>and pdf being indirectly supported through latex =
&quot;make ps / pdf&quot;) and is </FONT>
<BR><FONT SIZE=3D2>highly portable (Linux and Unix flavors, with =
executables for Windows, and </FONT>
<BR><FONT SIZE=3D2>Mac OS X also available).</FONT>
</P>

<P><FONT SIZE=3D2>Given that we maintain (and are about the only users =
of) cxx2html it would be </FONT>
<BR><FONT SIZE=3D2>better to now switch to doxygen.</FONT>
</P>

<P><FONT SIZE=3D2>As a prototype, I have doxygenated some the implement =
directory of aips (see </FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://www.aoc.nrao.edu/~ddebonis/doxygen" =
TARGET=3D"_blank">http://www.aoc.nrao.edu/~ddebonis/doxygen</A>) with a =
script I made using Ger's </FONT>
<BR><FONT SIZE=3D2>script as a translator.</FONT>
</P>

<P><FONT SIZE=3D2>Most of the mappings between cxx2html tags and =
doxygen tags have been made </FONT>
<BR><FONT SIZE=3D2>through Ger's perl script which I have attached to =
this proposal.</FONT>
</P>

<P><FONT SIZE=3D2>Summary:</FONT>
<BR><FONT SIZE=3D2>---------------</FONT>
<BR><FONT SIZE=3D2>Switching to doxygen will remove an AIPS++ created =
tool (cxx2html) that we </FONT>
<BR><FONT SIZE=3D2>maintain and replace it with a more standard code =
documentation tool.</FONT>
</P>

<P><FONT SIZE=3D2>Expected Impact:</FONT>
<BR><FONT SIZE=3D2>--------------------------</FONT>
<BR><FONT SIZE=3D2>Adoption of doxygen will require the translation of =
cxx2html tags to doxygen </FONT>
<BR><FONT SIZE=3D2>tags.&nbsp; Ger has written a script to do most of =
this already (a few additional </FONT>
<BR><FONT SIZE=3D2>tags need to be added to the translator) and I have =
already created an upper </FONT>
<BR><FONT SIZE=3D2>level script to drive the translator.</FONT>
</P>

<P><FONT SIZE=3D2>Changes will need to be put in place in the build =
system to replace cxx2html </FONT>
<BR><FONT SIZE=3D2>with doxygen, pointers to obtaining doxygen will =
need to be put in the </FONT>
<BR><FONT SIZE=3D2>documentation as well as how we expect to use =
doxygen.&nbsp; Also, a doxygen </FONT>
<BR><FONT SIZE=3D2>configuration file (which has already been created) =
will be added that </FONT>
<BR><FONT SIZE=3D2>defines how doxygen parses and presents the =
documentation.</FONT>
</P>

<P><FONT SIZE=3D2>Since this change will touch nearly every file, I =
believe that a code freeze </FONT>
<BR><FONT SIZE=3D2>(of less than half a day) should occur once the =
scripts have been refined and </FONT>
<BR><FONT SIZE=3D2>thoroughly tested.</FONT>
</P>

<P><FONT =
SIZE=3D2>_______________________________________________</FONT>
<BR><FONT SIZE=3D2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=3D2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" =
TARGET=3D"_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-deve=
lopers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C4504F.64700EAD--

From aips2-developers-admin at donar.cv.nrao.edu  Mon Jun 14 09:03:19 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5EG3JH9007739
	for <rrusk at localhost>; Mon, 14 Jun 2004 09:03:19 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Mon, 14 Jun 2004 09:03:19 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh1.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id M5CJSMNB; Mon, 14 Jun 2004 02:06:49 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5E662Sl020384;
	Mon, 14 Jun 2004 02:06:02 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5E661g17198;
	Mon, 14 Jun 2004 02:06:01 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5E659g17191
	for <aips2-developers at donar.cv.nrao.edu>; Mon, 14 Jun 2004 02:05:09 -0400
Received: from cv3.cv.nrao.edu (cv3.cv.nrao.edu [192.33.115.2])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5E659eL002279;
	Mon, 14 Jun 2004 02:05:09 -0400
Received: from server7.nfra.nl (server7.nfra.nl [192.87.1.57])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5E655Sl020272;
	Mon, 14 Jun 2004 02:05:05 -0400
Received: from NFRA-EXT-MTA by server7.nfra.nl
	with Novell_GroupWise; Mon, 14 Jun 2004 08:08:18 +0200
Message-ID: <s0cd5cf2.074 at server7.nfra.nl>
From: Ger van Diepen <diepen at astron.nl>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: aips2-developers at nrao.edu, jmcmulli at nrao.edu
Subject: Re: [aips2-developers]Doxygen Change Proposal
Date: Sun, 13 Jun 2004 23:07:45 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-Mailer: Novell GroupWise Internet Agent 6.5.2 Beta
X-BeenThere: Novell GroupWise Internet Agent 6.5.2 Beta
X-Mailman-Version: Novell GroupWise Internet Agent 6.5.2 Beta
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C451D5.C8B926F4"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 2

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C451D5.C8B926F4
Content-Type: text/plain;
	charset="iso-8859-1"

I agree it makes sense to switch to doxygen for the coding
documentation.
However, I have some comments on the proposal.
In general I find it too vague; it needs quite some elaboration.

1. I miss the details. How are the different cxx2html tags converted to
doxygen ones?
For example, what is done with tags like synopsis, etymology, todo,
etc. How are the different formats of the group tag dealt with? How
about references to groups?

2. I get the impression that all source files will be converted once
and that thereafter we have to use the doxygen style tags. I find the
doxygen tags very user-unfriendly and prefer very much to keep as much
as possible the cxx2html tags. 
Furthermore, in doxygen comments should be given in C-style using /**
*/. Very ugly. It makes it impossible to ignore comments when doing a
grep in source files.
I strongly prefer to convert only those tags that need handwork. All
tags that can be converted automatically should be kept and converted
on-the-fly using doxygen's input filter mechanism. This is what we use
for LOFAR as well.

3. Nothing is said about the module headers. How are they dealt with?

4. What is the main organization of the documentation? I find that
grouping things is not doxygen's strongest point.

Cheers,
- Ger

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C451D5.C8B926F4
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
charset=3Diso-8859-1">
<META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
5.5.2657.73">
<TITLE>Re: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

<P><FONT SIZE=3D2>I agree it makes sense to switch to doxygen for the =
coding</FONT>
<BR><FONT SIZE=3D2>documentation.</FONT>
<BR><FONT SIZE=3D2>However, I have some comments on the =
proposal.</FONT>
<BR><FONT SIZE=3D2>In general I find it too vague; it needs quite some =
elaboration.</FONT>
</P>

1. I miss the details. How are the different cxx2html =
tags converted to
 doxygen ones?
 For example, what is done with tags like synopsis, =
etymology, todo,
 etc. How are the different formats of the group tag =
dealt with? How
 about references to groups?

2. I get the impression that all source files will be =
converted once
 and that thereafter we have to use the doxygen style =
tags. I find the
 doxygen tags very user-unfriendly and prefer very =
much to keep as much
 as possible the cxx2html tags. 
 Furthermore, in doxygen comments should be given in =
C-style using /**
 */. Very ugly. It makes it impossible to ignore =
comments when doing a
 grep in source files.
 I strongly prefer to convert only those tags that =
need handwork. All
 tags that can be converted automatically should be =
kept and converted
 on-the-fly using doxygen's input filter mechanism. =
This is what we use
 for LOFAR as well.

3. Nothing is said about the module headers. How are =
they dealt with?

4. What is the main organization of the =
documentation? I find that
 grouping things is not doxygen's strongest =
point.

<P><FONT SIZE=3D2>Cheers,</FONT>
<BR><FONT SIZE=3D2>- Ger</FONT>
</P>

<P><FONT =
SIZE=3D2>_______________________________________________</FONT>
<BR><FONT SIZE=3D2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=3D2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" =
TARGET=3D"_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-deve=
lopers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C451D5.C8B926F4--

From aips2-developers-admin at donar.cv.nrao.edu  Mon Jun 14 09:03:29 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5EG3JHO007739
	for <rrusk at localhost>; Mon, 14 Jun 2004 09:03:29 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Mon, 14 Jun 2004 09:03:29 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh1.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id M5CJTAJ7; Mon, 14 Jun 2004 11:02:31 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5EF01Sl004307;
	Mon, 14 Jun 2004 11:00:02 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5EF01g07762;
	Mon, 14 Jun 2004 11:00:01 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5EExPg07739
	for <aips2-developers at donar.cv.nrao.edu>; Mon, 14 Jun 2004 10:59:25 -0400
Received: from revere.aoc.nrao.edu (revere.aoc.nrao.edu [146.88.1.15])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5EExOeL022691;
	Mon, 14 Jun 2004 10:59:24 -0400
Received: from demeter.aoc.nrao.edu (demeter [146.88.10.132])
	by revere.aoc.nrao.edu (8.11.6/8.11.6) with ESMTP id i5EExGN08094;
	Mon, 14 Jun 2004 08:59:16 -0600
Received: from localhost (localhost [[UNIX: localhost]])
	by demeter.aoc.nrao.edu (8.12.8/8.12.8/Submit) id i5EExGmp016830;
	Mon, 14 Jun 2004 08:59:16 -0600
Message-ID: <200406140859.12444.ddebonis at nrao.edu>
From: David DeBonis <ddebonis at nrao.edu>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: Ger van Diepen <diepen at astron.nl>, aips2-developers at nrao.edu,
        jmcmulli at nrao.edu
Subject: Re: [aips2-developers]Doxygen Change Proposal
Date: Mon, 14 Jun 2004 07:59:12 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-BeenThere: aips2-developers at listmgr.cv.nrao.edu
X-Mailman-Version: aips2-developers at listmgr.cv.nrao.edu
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C45220.9DFA391D"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 3

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C45220.9DFA391D
Content-Type: text/plain;
	charset="iso-8859-1"

On Monday 14 June 2004 12:07 am, Ger van Diepen wrote:
> I agree it makes sense to switch to doxygen for the coding
> documentation.
> However, I have some comments on the proposal.
> In general I find it too vague; it needs quite some elaboration.
>
> 1. I miss the details. How are the different cxx2html tags converted
to
> doxygen ones?
> For example, what is done with tags like synopsis, etymology, todo,
> etc. How are the different formats of the group tag dealt with? How
> about references to groups?

 - todo is a direct mapping.
 - synopsis would map to full description
 - etc.

I don't see any issues with references to groups since they will be
section 
tagged and could be referenced (linked) by this tag name.

I agree the details may be vague, but the intention is quite clear and I
don't 
see the details being necessary since there isn't any issues in the
mappings 
(they are pretty much one-to-one).

>
> 2. I get the impression that all source files will be converted once
> and that thereafter we have to use the doxygen style tags. I find the
> doxygen tags very user-unfriendly and prefer very much to keep as much
> as possible the cxx2html tags.
> Furthermore, in doxygen comments should be given in C-style using /**
> */. Very ugly. It makes it impossible to ignore comments when doing a
> grep in source files.
> I strongly prefer to convert only those tags that need handwork. All
> tags that can be converted automatically should be kept and converted
> on-the-fly using doxygen's input filter mechanism. This is what we use
> for LOFAR as well.

Doxygen supports a few forms of comments, one being related to C++ //
which is 
what I was planning to use (therefore, there should be no difference
when 
grepping).  The form used will either be /// or //!.

I disagree on maintaining the existing format.  Why would we want to
support 
the format of comments yet not support cxx2html?  It seems
hypocritical...  I 
think we should divorce ourselves from any dependencies on the old
format 
(otherwise, we are supporting TWO formats).

>
> 3. Nothing is said about the module headers. How are they dealt with?

Doxygen supports module groupings.

>
> 4. What is the main organization of the documentation? I find that
> grouping things is not doxygen's strongest point.

I believe doxygen to be highly configurable.  Personally, I think the 
out-of-the-box format sufficient.  If you have any other sugestions, let
me 
know.

>
> Cheers,
> - Ger
>
> _______________________________________________
> Aips2-developers mailing list
> Aips2-developers at listmgr.cv.nrao.edu
> http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C45220.9DFA391D
Content-Type: text/html;
	charset="iso-8859-1"

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="MS Exchange Server version 5.5.2657.73">
<TITLE>Re: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

On Monday 14 June 2004 12:07 am, Ger van Diepen wrote:
 &gt; I agree it makes sense to switch to doxygen for the coding
 &gt; documentation.
 &gt; However, I have some comments on the proposal.
 &gt; In general I find it too vague; it needs quite some elaboration.
 &gt;
 &gt; 1. I miss the details. How are the different cxx2html tags converted to
 &gt; doxygen ones?
 &gt; For example, what is done with tags like synopsis, etymology, todo,
 &gt; etc. How are the different formats of the group tag dealt with? How
 &gt; about references to groups?

<P><FONT SIZE=2>&nbsp;- todo is a direct mapping.</FONT>
<BR><FONT SIZE=2>&nbsp;- synopsis would map to full description</FONT>
<BR><FONT SIZE=2>&nbsp;- etc.</FONT>
</P>

<P><FONT SIZE=2>I don't see any issues with references to groups since they will be section </FONT>
<BR><FONT SIZE=2>tagged and could be referenced (linked) by this tag name.</FONT>
</P>

<P><FONT SIZE=2>I agree the details may be vague, but the intention is quite clear and I don't </FONT>
<BR><FONT SIZE=2>see the details being necessary since there isn't any issues in the mappings </FONT>
<BR><FONT SIZE=2>(they are pretty much one-to-one).</FONT>
</P>

&gt;
 &gt; 2. I get the impression that all source files will be converted once
 &gt; and that thereafter we have to use the doxygen style tags. I find the
 &gt; doxygen tags very user-unfriendly and prefer very much to keep as much
 &gt; as possible the cxx2html tags.
 &gt; Furthermore, in doxygen comments should be given in C-style using /**
 &gt; */. Very ugly. It makes it impossible to ignore comments when doing a
 &gt; grep in source files.
 &gt; I strongly prefer to convert only those tags that need handwork. All
 &gt; tags that can be converted automatically should be kept and converted
 &gt; on-the-fly using doxygen's input filter mechanism. This is what we use
 &gt; for LOFAR as well.

<P><FONT SIZE=2>Doxygen supports a few forms of comments, one being related to C++ // which is </FONT>
<BR><FONT SIZE=2>what I was planning to use (therefore, there should be no difference when </FONT>
<BR><FONT SIZE=2>grepping).&nbsp; The form used will either be /// or //!.</FONT>
</P>

<P><FONT SIZE=2>I disagree on maintaining the existing format.&nbsp; Why would we want to support </FONT>
<BR><FONT SIZE=2>the format of comments yet not support cxx2html?&nbsp; It seems hypocritical...&nbsp; I </FONT>
<BR><FONT SIZE=2>think we should divorce ourselves from any dependencies on the old format </FONT>
<BR><FONT SIZE=2>(otherwise, we are supporting TWO formats).</FONT>
</P>

&gt;
 &gt; 3. Nothing is said about the module headers. How are they dealt with?

<P><FONT SIZE=2>Doxygen supports module groupings.</FONT>
</P>

&gt;
 &gt; 4. What is the main organization of the documentation? I find that
 &gt; grouping things is not doxygen's strongest point.

<P><FONT SIZE=2>I believe doxygen to be highly configurable.&nbsp; Personally, I think the </FONT>
<BR><FONT SIZE=2>out-of-the-box format sufficient.&nbsp; If you have any other sugestions, let me </FONT>
<BR><FONT SIZE=2>know.</FONT>
</P>

<P><FONT SIZE=2>&gt;</FONT>
<BR><FONT SIZE=2>&gt; Cheers,</FONT>
<BR><FONT SIZE=2>&gt; - Ger</FONT>
<BR><FONT SIZE=2>&gt;</FONT>
<BR><FONT SIZE=2>&gt; _______________________________________________</FONT>
<BR><FONT SIZE=2>&gt; Aips2-developers mailing list</FONT>
<BR><FONT SIZE=2>&gt; Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=2>&gt; <A HREF="http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" TARGET="_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers</A></FONT>
</P>

<P><FONT SIZE=2>_______________________________________________</FONT>
<BR><FONT SIZE=2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=2><A HREF="http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" TARGET="_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C45220.9DFA391D--

From aips2-developers-admin at donar.cv.nrao.edu  Tue Jun 15 16:44:17 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5FNiFHC008800
	for <rrusk at localhost>; Tue, 15 Jun 2004 16:44:17 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Tue, 15 Jun 2004 16:44:17 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh1.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id M5CJ4JGZ; Tue, 15 Jun 2004 02:41:45 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5F6f3Sl016886;
	Tue, 15 Jun 2004 02:41:03 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5F6f3g05094;
	Tue, 15 Jun 2004 02:41:03 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5F6ecg05085
	for <aips2-developers at donar.cv.nrao.edu>; Tue, 15 Jun 2004 02:40:38 -0400
Received: from cv3.cv.nrao.edu (cv3.cv.nrao.edu [192.33.115.2])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5F6eceP030337;
	Tue, 15 Jun 2004 02:40:38 -0400
Received: from server7.nfra.nl (server7.nfra.nl [192.87.1.57])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5F6eXSl016840;
	Tue, 15 Jun 2004 02:40:34 -0400
Received: from NFRA-EXT-MTA by server7.nfra.nl
	with Novell_GroupWise; Tue, 15 Jun 2004 08:43:48 +0200
Message-ID: <s0ceb6c4.072 at server7.nfra.nl>
From: Ger van Diepen <diepen at astron.nl>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: aips2-developers at nrao.edu, ddebonis at nrao.edu, jmcmulli at nrao.edu
Subject: Re: [aips2-developers]Doxygen Change Proposal
Date: Mon, 14 Jun 2004 23:43:20 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-Mailer: Novell GroupWise Internet Agent 6.5.2 Beta
X-BeenThere: Novell GroupWise Internet Agent 6.5.2 Beta
X-Mailman-Version: Novell GroupWise Internet Agent 6.5.2 Beta
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C452A3.D5DBBB59"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 4

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C452A3.D5DBBB59
Content-Type: text/plain;
	charset="iso-8859-1"

David,

I do not agree with you.
I think that a change proposal should give more detail about how the
change will be done and what impact it has. Otherwise it is very hard
for people to comment. It should generate discussion.

cxx2html has several tags which need to be mapped to doxygen. Are they
all looked at and is it sure that they can be mapped in an automatic
way? I'm not so sure about that. For instance, how is dealt with
<summary> or <linkfrom>?
See code/doc/html/cxx2html.html for all possible tags. I believe almost
all thse tags are actively used.
Links cannot be converted to hard-coded links using <a href=>. So what
will be used for them? \anchor can only be used with \page, so it is
very limited.

I find doxygen a reasonable tool, but I don't like its archaic
documentation tags. I find the xml/html-style used by cxx2html much
better. Something like <group> </group> is easier then @{ and @}
Therefore I would like to keep as much as possible the current tags and
convert them on-the-fly. I cannot see any objection to that.
In the doxygen manual I have, I don't see that // is supported. It only
supports /// and //!. Furthermore it says that when using this style,
you need at least two comment lines. For me this is another argument to
convert on-the-fly.

doxygen supports modules by means of tags \defgroup and \ingroup. Using
them has implications when a file gets moved. It should be rather easy
to generate those tags on-the-fly.
cxx2html does it automatically based on the directory structure, so
moving files has no implications.

What I miss is whether you plan to generate the graphs, thus whether
sites need to install the dot tool from graphviz. It has some impact.
Doxygen generates a stripped version of the header files and generates
a link to them. A discussion topic  could be if you want to show the
copyright header in them.
Another question is whether you only feed the .h files to doxygen or
also the .cc files.
Has doxygen means for leaving out some internal comments which are
indicated with //# for cxx2html?

Sometimes notes refer to class documentation. Can that still be done
and if so, how?
Will such links also be changed in the conversion process?

Cheers,
- Ger

>>> David DeBonis <ddebonis at nrao.edu> 14-Jun-04 16:59 >>>
On Monday 14 June 2004 12:07 am, Ger van Diepen wrote:
> I agree it makes sense to switch to doxygen for the coding
> documentation.
> However, I have some comments on the proposal.
> In general I find it too vague; it needs quite some elaboration.
>
> 1. I miss the details. How are the different cxx2html tags converted
to
> doxygen ones?
> For example, what is done with tags like synopsis, etymology, todo,
> etc. How are the different formats of the group tag dealt with? How
> about references to groups?

 - todo is a direct mapping.
 - synopsis would map to full description
 - etc.

I don't see any issues with references to groups since they will be
section 
tagged and could be referenced (linked) by this tag name.

I agree the details may be vague, but the intention is quite clear and
I don't 
see the details being necessary since there isn't any issues in the
mappings 
(they are pretty much one-to-one).

>
> 2. I get the impression that all source files will be converted once
> and that thereafter we have to use the doxygen style tags. I find
the
> doxygen tags very user-unfriendly and prefer very much to keep as
much
> as possible the cxx2html tags.
> Furthermore, in doxygen comments should be given in C-style using
/**
> */. Very ugly. It makes it impossible to ignore comments when doing
a
> grep in source files.
> I strongly prefer to convert only those tags that need handwork. All
> tags that can be converted automatically should be kept and
converted
> on-the-fly using doxygen's input filter mechanism. This is what we
use
> for LOFAR as well.

Doxygen supports a few forms of comments, one being related to C++ //
which is 
what I was planning to use (therefore, there should be no difference
when 
grepping).  The form used will either be /// or //!.

I disagree on maintaining the existing format.  Why would we want to
support 
the format of comments yet not support cxx2html?  It seems
hypocritical...  I 
think we should divorce ourselves from any dependencies on the old
format 
(otherwise, we are supporting TWO formats).

>
> 3. Nothing is said about the module headers. How are they dealt
with?

Doxygen supports module groupings.

>
> 4. What is the main organization of the documentation? I find that
> grouping things is not doxygen's strongest point.

I believe doxygen to be highly configurable.  Personally, I think the 
out-of-the-box format sufficient.  If you have any other sugestions,
let me 
know.

>
> Cheers,
> - Ger
>
> _______________________________________________
> Aips2-developers mailing list
> Aips2-developers at listmgr.cv.nrao.edu 
> http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers 

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu 
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C452A3.D5DBBB59
Content-Type: text/html;
	charset="iso-8859-1"

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="MS Exchange Server version 5.5.2657.73">
<TITLE>Re: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

<P><FONT SIZE=2>David,</FONT>
</P>

I do not agree with you.
 I think that a change proposal should give more detail about how the
 change will be done and what impact it has. Otherwise it is very hard
 for people to comment. It should generate discussion.

cxx2html has several tags which need to be mapped to doxygen. Are they
 all looked at and is it sure that they can be mapped in an automatic
 way? I'm not so sure about that. For instance, how is dealt with
 &lt;summary&gt; or &lt;linkfrom&gt;?
 See code/doc/html/cxx2html.html for all possible tags. I believe almost
 all thse tags are actively used.
 Links cannot be converted to hard-coded links using &lt;a href=&gt;. So what
 will be used for them? \anchor can only be used with \page, so it is
 very limited.

I find doxygen a reasonable tool, but I don't like its archaic
 documentation tags. I find the xml/html-style used by cxx2html much
 better. Something like &lt;group&gt; &lt;/group&gt; is easier then @{ and @}
 Therefore I would like to keep as much as possible the current tags and
 convert them on-the-fly.&nbsp; I cannot see any objection to that.
 In the doxygen manual I have, I don't see that // is supported. It only
 supports /// and //!. Furthermore it says that when using this style,
 you need at least two comment lines. For me this is another argument to
 convert on-the-fly.

doxygen supports modules by means of tags \defgroup and \ingroup. Using
 them has implications when a file gets moved. It should be rather easy
 to generate those tags on-the-fly.
 cxx2html does it automatically based on the directory structure, so
 moving files has no implications.

What I miss is whether you plan to generate the graphs, thus whether
 sites need to install the dot tool from graphviz. It has some impact.
 Doxygen generates a stripped version of the header files and generates
 a link to them. A discussion topic&nbsp; could be if you want to show the
 copyright header in them.
 Another question is whether you only feed the .h files to doxygen or
 also the .cc files.
 Has doxygen means for leaving out some internal comments which are
 indicated with //# for cxx2html?

Sometimes notes refer to class documentation. Can that still be done
 and if so, how?
 Will such links also be changed in the conversion process?

<P><FONT SIZE=2>Cheers,</FONT>
<BR><FONT SIZE=2>- Ger</FONT>
</P>
<BR>

&gt;&gt;&gt; David DeBonis &lt;ddebonis at nrao.edu&gt; 14-Jun-04 16:59 &gt;&gt;&gt;
 On Monday 14 June 2004 12:07 am, Ger van Diepen wrote:
 &gt; I agree it makes sense to switch to doxygen for the coding
 &gt; documentation.
 &gt; However, I have some comments on the proposal.
 &gt; In general I find it too vague; it needs quite some elaboration.
 &gt;
 &gt; 1. I miss the details. How are the different cxx2html tags converted
 to
 &gt; doxygen ones?
 &gt; For example, what is done with tags like synopsis, etymology, todo,
 &gt; etc. How are the different formats of the group tag dealt with? How
 &gt; about references to groups?

<P><FONT SIZE=2>&nbsp;- todo is a direct mapping.</FONT>
<BR><FONT SIZE=2>&nbsp;- synopsis would map to full description</FONT>
<BR><FONT SIZE=2>&nbsp;- etc.</FONT>
</P>

<P><FONT SIZE=2>I don't see any issues with references to groups since they will be</FONT>
<BR><FONT SIZE=2>section </FONT>
<BR><FONT SIZE=2>tagged and could be referenced (linked) by this tag name.</FONT>
</P>

<P><FONT SIZE=2>I agree the details may be vague, but the intention is quite clear and</FONT>
<BR><FONT SIZE=2>I don't </FONT>
<BR><FONT SIZE=2>see the details being necessary since there isn't any issues in the</FONT>
<BR><FONT SIZE=2>mappings </FONT>
<BR><FONT SIZE=2>(they are pretty much one-to-one).</FONT>
</P>

&gt;
 &gt; 2. I get the impression that all source files will be converted once
 &gt; and that thereafter we have to use the doxygen style tags. I find
 the
 &gt; doxygen tags very user-unfriendly and prefer very much to keep as
 much
 &gt; as possible the cxx2html tags.
 &gt; Furthermore, in doxygen comments should be given in C-style using
 /**
 &gt; */. Very ugly. It makes it impossible to ignore comments when doing
 a
 &gt; grep in source files.
 &gt; I strongly prefer to convert only those tags that need handwork. All
 &gt; tags that can be converted automatically should be kept and
 converted
 &gt; on-the-fly using doxygen's input filter mechanism. This is what we
 use
 &gt; for LOFAR as well.

<P><FONT SIZE=2>Doxygen supports a few forms of comments, one being related to C++ //</FONT>
<BR><FONT SIZE=2>which is </FONT>
<BR><FONT SIZE=2>what I was planning to use (therefore, there should be no difference</FONT>
<BR><FONT SIZE=2>when </FONT>
<BR><FONT SIZE=2>grepping).&nbsp; The form used will either be /// or //!.</FONT>
</P>

<P><FONT SIZE=2>I disagree on maintaining the existing format.&nbsp; Why would we want to</FONT>
<BR><FONT SIZE=2>support </FONT>
<BR><FONT SIZE=2>the format of comments yet not support cxx2html?&nbsp; It seems</FONT>
<BR><FONT SIZE=2>hypocritical...&nbsp; I </FONT>
<BR><FONT SIZE=2>think we should divorce ourselves from any dependencies on the old</FONT>
<BR><FONT SIZE=2>format </FONT>
<BR><FONT SIZE=2>(otherwise, we are supporting TWO formats).</FONT>
</P>

&gt;
 &gt; 3. Nothing is said about the module headers. How are they dealt
 with?

<P><FONT SIZE=2>Doxygen supports module groupings.</FONT>
</P>

&gt;
 &gt; 4. What is the main organization of the documentation? I find that
 &gt; grouping things is not doxygen's strongest point.

<P><FONT SIZE=2>I believe doxygen to be highly configurable.&nbsp; Personally, I think the </FONT>
<BR><FONT SIZE=2>out-of-the-box format sufficient.&nbsp; If you have any other sugestions,</FONT>
<BR><FONT SIZE=2>let me </FONT>
<BR><FONT SIZE=2>know.</FONT>
</P>

<P><FONT SIZE=2>&gt;</FONT>
<BR><FONT SIZE=2>&gt; Cheers,</FONT>
<BR><FONT SIZE=2>&gt; - Ger</FONT>
<BR><FONT SIZE=2>&gt;</FONT>
<BR><FONT SIZE=2>&gt; _______________________________________________</FONT>
<BR><FONT SIZE=2>&gt; Aips2-developers mailing list</FONT>
<BR><FONT SIZE=2>&gt; Aips2-developers at listmgr.cv.nrao.edu </FONT>
<BR><FONT SIZE=2>&gt; <A HREF="http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" TARGET="_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers</A> </FONT>
</P>

<P><FONT SIZE=2>_______________________________________________</FONT>
<BR><FONT SIZE=2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=2>Aips2-developers at listmgr.cv.nrao.edu </FONT>
<BR><FONT SIZE=2><A HREF="http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" TARGET="_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers</A></FONT>
</P>

<P><FONT SIZE=2>_______________________________________________</FONT>
<BR><FONT SIZE=2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=2><A HREF="http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" TARGET="_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C452A3.D5DBBB59--

From aips2-developers-admin at donar.cv.nrao.edu  Wed Jun 16 07:19:31 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5GEJTHD009778
	for <rrusk at localhost>; Wed, 16 Jun 2004 07:19:31 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Wed, 16 Jun 2004 07:19:31 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh2.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id MT4ANL7F; Wed, 16 Jun 2004 03:13:13 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5G7D1Sl003148;
	Wed, 16 Jun 2004 03:13:01 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5G7D1g22546;
	Wed, 16 Jun 2004 03:13:01 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5G7C4g22534
	for <aips2-developers at donar.cv.nrao.edu>; Wed, 16 Jun 2004 03:12:04 -0400
Received: from cv3.cv.nrao.edu (cv3.cv.nrao.edu [192.33.115.2])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5G7C3eL010310;
	Wed, 16 Jun 2004 03:12:04 -0400
Received: from csiromail2.vic.csiro.au (csiromail2.vic.csiro.au [138.194.2.13])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5G7C0Sl002926;
	Wed, 16 Jun 2004 03:12:01 -0400
Received: from csiromail2.vic.csiro.au (localhost.localdomain [127.0.0.1])
	by localhost.vic.csiro.au (Postfix) with ESMTP
	id 5834A5404A; Wed, 16 Jun 2004 17:11:59 +1000 (EST)
Received: from exgw1-mel.nexus.csiro.au (exgw1-mel.nexus.csiro.au [138.194.3.56])
	by csiromail2.vic.csiro.au (Postfix) with ESMTP
	id 4CBE254046; Wed, 16 Jun 2004 17:11:59 +1000 (EST)
Received: from EXVIC2-MEL.vic.csiro.au ([138.194.3.52]) by exgw1-mel.nexus.csiro.au with Microsoft SMTPSVC(5.0.2195.6713);
	 Wed, 16 Jun 2004 17:11:59 +1000
Received: from EXNSW2-SYD.nsw.csiro.au ([130.155.3.52]) by EXVIC2-MEL.vic.csiro.au with Microsoft SMTPSVC(5.0.2195.6713);
	 Wed, 16 Jun 2004 17:11:59 +1000
Message-ID: <2B599A9926362947A065B296D4F4573C232E23 at exnsw2-syd.nexus.csiro.au>
From: Wim.Brouw at csiro.au
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: jmcmulli at nrao.edu, aips2-developers at nrao.edu
Cc: Wim.Brouw at csiro.au
Subject: RE: [aips2-developers]Doxygen Change Proposal
Date: Wed, 16 Jun 2004 00:11:58 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-MIMEOLE: Produced By Microsoft Exchange V6.0.6487.1
Content-Class: Produced By Microsoft Exchange V6.0.6487.1
X-MS-Has-Attach: Produced By Microsoft Exchange V6.0.6487.1
X-OriginalArrivalTime: Produced By Microsoft Exchange V6.0.6487.1
X-MIME-Autoconverted: Produced By Microsoft Exchange V6.0.6487.1
X-BeenThere: Produced By Microsoft Exchange V6.0.6487.1
X-Mailman-Version: Produced By Microsoft Exchange V6.0.6487.1
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C45371.639823C9"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 5

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C45371.639823C9
Content-Type: text/plain;
	charset="iso-8859-1"

A lot of comments made already, no need to repeat all of them. I agree
with comments that the proposal is too basic, and does neither list the
work to be done, nor the proposed goal in output and usability.

Documentation has two sides:
1. To enable comments and annotations to be easily interspersed in code
to clarify and explain issues. I.e. the input
2. To gather the information and give a proper overview of the total
package; its interconnections and dependencies etc. I.e. the output to
be used by the 'user'

Replacing cxx2html with doxygen(or maybe some other package) for 2):
seems like a good idea in general, although I miss in the examples I
have seen propoer clustering of classes: everything is alphabetical
rather than layered in modules, packages or whatever. Only namespaces
seem to be usable as layers.
Apart from that, the output including dependencies and 'used by' is
valuable.
I do not know enough about output options i\f some graphic tree
structure is possible as well?

Annotation using doxygen seems to me not the right way to go:
	o the annotation method is old-fashioned, and does not belong in
the extensible sgml (like xml) class of tagging.
	o the number of xml parsers out there, makes having of
front-ends based on sgml tags much easier than any other tagging method
	o I do not like the 'active commenting mode': it is less natural
for standard flow of commentary (and changes) to have to specify if a
comment is meant to be hidden, rather than that iks to be exposed (and
in the end better for the information passing from orignator to end
user).
	o I definitely like Ger's idea of having a script front-end to
on-the-fly format the input into something acceptable and usable by
doxygen. This also makes it easy to move at some future date from
doxygen to other, maybe improved backends that can also handle python
and/or other scripting languages to generate documentation from source
code. (I hope that doxygen is in principle usabel for that, it is one of
the biggest problems in the doc system that scripts have to be written
three times to get documentation and meta information).

Documentation is best usable is information is organised in certain
orders. This means that a kind of 'template' to be used by writers is
essential (it is e.g. much easier to follow if examples always precede
or always follow the explanations; rather than some random structure.
Also, even using the doxygen native style of annotation, there must be
scripts that:
a. check if the doc-template-rules are being followed (much easier to do
straight away rather than at a later stage)
b. convert any non-doxygen tag that has to be used to enable e.g. proper
referencing; or any formatting not supported easily (formulas?,
sup/sub?) can be 'translated' into something half-usable at the minimum
c. cater for errors in doxygen (according to reports I read doxygen
cannot cope with duplicate class declarations, like e.g. in [partial]
specializations: creating pseudo names could solve this)

Before any change, it is necessary to clean up existing .h files so the
list of errors and warnings generated by cxx2html are resolved: now is
the time to do it

Should the switch be done before, after or during lib split and
namespace? I wouyld suggest after namespace: namespaces are not so
niceky handled by cxx2html, and correcting of existing errors is better
done first with cxx2html

Coding templates shoudl be revised, probably simplified and py and j
templates should be prepared etc (including revised copyright? -- should
be discussed on coordinating group, like namespace name).

Any idea about the amount of work that is necessary to create a usable
system in the end, and the necessary maintenance at library maintainers
of supporting software?

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C45371.639823C9
Content-Type: text/html;
	charset="iso-8859-1"

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="MS Exchange Server version 5.5.2657.73">
<TITLE>RE: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

A lot of comments made already, no need to repeat all of them. I agree
 with comments that the proposal is too basic, and does neither list the
 work to be done, nor the proposed goal in output and usability.

Documentation has two sides:
 1. To enable comments and annotations to be easily interspersed in code
 to clarify and explain issues. I.e. the input
 2. To gather the information and give a proper overview of the total
 package; its interconnections and dependencies etc. I.e. the output to
 be used by the 'user'

Replacing cxx2html with doxygen(or maybe some other package) for 2):
 seems like a good idea in general, although I miss in the examples I
 have seen propoer clustering of classes: everything is alphabetical
 rather than layered in modules, packages or whatever. Only namespaces
 seem to be usable as layers.
 Apart from that, the output including dependencies and 'used by' is
 valuable.
 I do not know enough about output options i\f some graphic tree
 structure is possible as well?

Annotation using doxygen seems to me not the right way to go:
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; o the annotation method is old-fashioned, and does not belong in
 the extensible sgml (like xml) class of tagging.
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; o the number of xml parsers out there, makes having of
 front-ends based on sgml tags much easier than any other tagging method
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; o I do not like the 'active commenting mode': it is less natural
 for standard flow of commentary (and changes) to have to specify if a
 comment is meant to be hidden, rather than that iks to be exposed (and
 in the end better for the information passing from orignator to end
 user).
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; o I definitely like Ger's idea of having a script front-end to
 on-the-fly format the input into something acceptable and usable by
 doxygen. This also makes it easy to move at some future date from
 doxygen to other, maybe improved backends that can also handle python
 and/or other scripting languages to generate documentation from source
 code. (I hope that doxygen is in principle usabel for that, it is one of
 the biggest problems in the doc system that scripts have to be written
 three times to get documentation and meta information).

Documentation is best usable is information is organised in certain
 orders. This means that a kind of 'template' to be used by writers is
 essential (it is e.g. much easier to follow if examples always precede
 or always follow the explanations; rather than some random structure.
 Also, even using the doxygen native style of annotation, there must be
 scripts that:
 a. check if the doc-template-rules are being followed (much easier to do
 straight away rather than at a later stage)
 b. convert any non-doxygen tag that has to be used to enable e.g. proper
 referencing; or any formatting not supported easily (formulas?,
 sup/sub?) can be 'translated' into something half-usable at the minimum
 c. cater for errors in doxygen (according to reports I read doxygen
 cannot cope with duplicate class declarations, like e.g. in [partial]
 specializations: creating pseudo names could solve this)

<P><FONT SIZE=2>Before any change, it is necessary to clean up existing .h files so the</FONT>
<BR><FONT SIZE=2>list of errors and warnings generated by cxx2html are resolved: now is</FONT>
<BR><FONT SIZE=2>the time to do it</FONT>
</P>

Should the switch be done before, after or during lib split and
 namespace? I wouyld suggest after namespace: namespaces are not so
 niceky handled by cxx2html, and correcting of existing errors is better
 done first with cxx2html

Coding templates shoudl be revised, probably simplified and py and j
 templates should be prepared etc (including revised copyright? -- should
 be discussed on coordinating group, like namespace name).

<P><FONT SIZE=2>Any idea about the amount of work that is necessary to create a usable</FONT>
<BR><FONT SIZE=2>system in the end, and the necessary maintenance at library maintainers</FONT>
<BR><FONT SIZE=2>of supporting software?</FONT>
</P>

<P><FONT SIZE=2>_______________________________________________</FONT>
<BR><FONT SIZE=2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=2><A HREF="http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" TARGET="_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C45371.639823C9--

From aips2-developers-admin at donar.cv.nrao.edu  Wed Jun 16 18:39:49 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5H1dmHC009904
	for <rrusk at localhost>; Wed, 16 Jun 2004 18:39:49 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Wed, 16 Jun 2004 18:39:49 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh2.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id MT4A3PD9; Wed, 16 Jun 2004 12:36:10 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5GGa2Sl016618;
	Wed, 16 Jun 2004 12:36:02 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5GGa2g14371;
	Wed, 16 Jun 2004 12:36:02 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5GGZ8g14356
	for <aips2-developers at donar.cv.nrao.edu>; Wed, 16 Jun 2004 12:35:08 -0400
Received: from revere.aoc.nrao.edu (revere.aoc.nrao.edu [146.88.1.15])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5GGZ7eL026814
	for <aips2-developers at nrao.edu>; Wed, 16 Jun 2004 12:35:07 -0400
Received: from SHACKLETON (SHACKLETON.aoc.nrao.edu [146.88.1.69])
	by revere.aoc.nrao.edu (8.11.6/8.11.6) with ESMTP id i5GGZ4N17455
	for <aips2-developers at nrao.edu>; Wed, 16 Jun 2004 10:35:04 -0600
Message-ID: <200406161635.i5GGZ4N17455 at revere.aoc.nrao.edu>
From: Brian Glendenning <bglenden at nrao.edu>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: aips2-developers at nrao.edu
Subject: RE: [aips2-developers]Doxygen Change Proposal
Date: Wed, 16 Jun 2004 09:35:00 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-Mailer: Microsoft Office Outlook, Build 11.0.5510
X-MimeOLE: Microsoft Office Outlook, Build 11.0.5510
X-BeenThere: Microsoft Office Outlook, Build 11.0.5510
X-Mailman-Version: Microsoft Office Outlook, Build 11.0.5510
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C453C0.084E6B82"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 6

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C453C0.084E6B82
Content-Type: text/plain;
	charset="iso-8859-1"

If we are not going to change our tags, then what we are really doing is
reimplementing cxx2html rather than using doxygen (which becomes then an
implementation detail). On the other hand if we want to switch from
cxx2html
we should really switch rather than end up in some intermediate
situation
where we still have to maintain our own peculiar software, cannot just
tell
people to read the standard doxygen information, etc.

Cheers,
Brian

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C453C0.084E6B82
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
charset=3Diso-8859-1">
<META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
5.5.2657.73">
<TITLE>RE: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

If we are not going to change our tags, then what we =
are really doing is
 reimplementing cxx2html rather than using doxygen =
(which becomes then an
 implementation detail). On the other hand if we want =
to switch from cxx2html
 we should really switch rather than end up in some =
intermediate situation
 where we still have to maintain our own peculiar =
software, cannot just tell
 people to read the standard doxygen information, =
etc.

<P><FONT SIZE=3D2>Cheers,</FONT>
<BR><FONT SIZE=3D2>Brian</FONT>
</P>

<P><FONT =
SIZE=3D2>_______________________________________________</FONT>
<BR><FONT SIZE=3D2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=3D2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" =
TARGET=3D"_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-deve=
lopers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C453C0.084E6B82--

From aips2-developers-admin at donar.cv.nrao.edu  Thu Jun 17 07:03:21 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5HE3KHB010670
	for <rrusk at localhost>; Thu, 17 Jun 2004 07:03:21 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Thu, 17 Jun 2004 07:03:21 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh1.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id NBMQX9ZH; Thu, 17 Jun 2004 04:15:14 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5H8F1Sl003959;
	Thu, 17 Jun 2004 04:15:02 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5H8F1g08585;
	Thu, 17 Jun 2004 04:15:01 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5H8Erg08566
	for <aips2-developers at donar.cv.nrao.edu>; Thu, 17 Jun 2004 04:14:53 -0400
Received: from cv3.cv.nrao.edu (cv3.cv.nrao.edu [192.33.115.2])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5H8EreL004925;
	Thu, 17 Jun 2004 04:14:53 -0400
Received: from server7.nfra.nl (server7.nfra.nl [192.87.1.57])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5H8EmSl003930;
	Thu, 17 Jun 2004 04:14:48 -0400
Received: from NFRA-EXT-MTA by server7.nfra.nl
	with Novell_GroupWise; Thu, 17 Jun 2004 10:18:04 +0200
Message-ID: <s0d16fdc.084 at server7.nfra.nl>
From: Ger van Diepen <diepen at astron.nl>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: aips2-developers at nrao.edu, bglenden at nrao.edu
Subject: RE: [aips2-developers]Doxygen Change Proposal
Date: Thu, 17 Jun 2004 01:17:35 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-Mailer: Novell GroupWise Internet Agent 6.5.2 Beta
X-BeenThere: Novell GroupWise Internet Agent 6.5.2 Beta
X-Mailman-Version: Novell GroupWise Internet Agent 6.5.2 Beta
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C45443.3824DE21"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 7

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C45443.3824DE21
Content-Type: text/plain;
	charset="iso-8859-1"

I proposed to use doxygen, but keep as much as possible the cxx2html
tags because IMHO they are superior to the rather ad-hoc doxygen tags. I
think that in this way you mix the best of both worlds and you achieve
that the AIPS++ developers don't have to learn a new documentation
language.
IMO another advantage is that (in principle) you protect the users from
the very extensive set of doxygen tags.
Another advantage is that you can do the grouping in packages
automatically, so moving a file does not require changing a
documentation tag.
Also note that doxygen supports the common html tags; probably they
learned that people like to use such tags.

I don't agree it means we have to reimplement cx22html; it means you
have a simple and small Perl script to convert the tags. That script has
to be made anyway.
Furthermore, if we have to start using /* */ for comments, we are
partly back in the old C-world. I don't think anybody would like that.
Certainly I won't.

I agree with Wim's comments that someday you might want to switch to
some other (better) tool.
Converting from the doxygen tags seems more difficult to me than
converting from the more limited and structured cxx2html tags.

In development time it won't make any difference. The conversion script
always has to be made.
In run-time it won't hardly make any difference. Running the script as
an input-filter is fast enough.

Cheers,
- Ger

>>> "Brian Glendenning" <bglenden at nrao.edu> 16-Jun-04 18:35 >>>
If we are not going to change our tags, then what we are really doing
is
reimplementing cxx2html rather than using doxygen (which becomes then
an
implementation detail). On the other hand if we want to switch from
cxx2html
we should really switch rather than end up in some intermediate
situation
where we still have to maintain our own peculiar software, cannot just
tell
people to read the standard doxygen information, etc.

Cheers,
Brian

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu 
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C45443.3824DE21
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
charset=3Diso-8859-1">
<META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
5.5.2657.73">
<TITLE>RE: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

I proposed to use doxygen, but keep as much as =
possible the cxx2html
 tags because IMHO they are superior to the rather =
ad-hoc doxygen tags. I
 think that in this way you mix the best of both =
worlds and you achieve
 that the AIPS++ developers don't have to learn a new =
documentation
 language.
 IMO another advantage is that (in principle) you =
protect the users from
 the very extensive set of doxygen tags.
 Another advantage is that you can do the grouping in =
packages
 automatically, so moving a file does not require =
changing a
 documentation tag.
 Also note that doxygen supports the common html =
tags; probably they
 learned that people like to use such tags.

I don't agree it means we have to reimplement =
cx22html; it means you
 have a simple and small Perl script to convert the =
tags. That script has
 to be made anyway.
 Furthermore, if we have to start using /* */ for =
comments, we are
 partly back in the old C-world. I don't think =
anybody would like that.
 Certainly I won't.

<P><FONT SIZE=3D2>I agree with Wim's comments that someday you might =
want to switch to</FONT>
<BR><FONT SIZE=3D2>some other (better) tool.</FONT>
<BR><FONT SIZE=3D2>Converting from the doxygen tags seems more =
difficult to me than</FONT>
<BR><FONT SIZE=3D2>converting from the more limited and structured =
cxx2html tags.</FONT>
</P>

In development time it won't make any difference. The =
conversion script
 always has to be made.
 In run-time it won't hardly make any difference. =
Running the script as
 an input-filter is fast enough.

<P><FONT SIZE=3D2>Cheers,</FONT>
<BR><FONT SIZE=3D2>- Ger</FONT>
</P>
<BR>

&gt;&gt;&gt; &quot;Brian Glendenning&quot; =
&lt;bglenden at nrao.edu&gt; 16-Jun-04 18:35 &gt;&gt;&gt;
 If we are not going to change our tags, then what we =
are really doing
 is
 reimplementing cxx2html rather than using doxygen =
(which becomes then
 an
 implementation detail). On the other hand if we want =
to switch from
 cxx2html
 we should really switch rather than end up in some =
intermediate
 situation
 where we still have to maintain our own peculiar =
software, cannot just
 tell
 people to read the standard doxygen information, =
etc.

<P><FONT SIZE=3D2>Cheers,</FONT>
<BR><FONT SIZE=3D2>Brian</FONT>
</P>

<P><FONT =
SIZE=3D2>_______________________________________________</FONT>
<BR><FONT SIZE=3D2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=3D2>Aips2-developers at listmgr.cv.nrao.edu </FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" =
TARGET=3D"_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-deve=
lopers</A></FONT>
</P>

<P><FONT =
SIZE=3D2>_______________________________________________</FONT>
<BR><FONT SIZE=3D2>Aips2-developers mailing list</FONT>
<BR><FONT SIZE=3D2>Aips2-developers at listmgr.cv.nrao.edu</FONT>
<BR><FONT SIZE=3D2><A =
HREF=3D"http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers" =
TARGET=3D"_blank">http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-deve=
lopers</A></FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01C45443.3824DE21--

From aips2-developers-admin at donar.cv.nrao.edu  Thu Jun 17 16:20:06 2004
Return-Path: <aips2-developers-admin at donar.cv.nrao.edu>
Received: from localhost (mekbuda.drao.nrc.ca [127.0.0.1])
	by mekbuda.drao.nrc.ca (8.12.10/8.12.10) with ESMTP id i5HNK5HA010779
	for <rrusk at localhost>; Thu, 17 Jun 2004 16:20:06 -0700
Received: from nrcwstex1.ic.nrc.ca [192.139.116.29]
	by localhost with IMAP (fetchmail-6.2.0)
	for rrusk at localhost (single-drop); Thu, 17 Jun 2004 16:20:06 -0700 (PDT)
Received: from cv3.cv.nrao.edu (nrao.edu [192.33.115.2]) by nrcmrdbh1.imsb.nrc.ca with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2657.72)
	id NBMQYSSF; Thu, 17 Jun 2004 11:57:34 -0400
Received: from donar.cv.nrao.edu (donar.cv.nrao.edu [192.33.115.6])
	by cv3.cv.nrao.edu (8.12.8/8.12.8/cv-ws-8.12) with ESMTP id i5HFv1Sl024749;
	Thu, 17 Jun 2004 11:57:02 -0400
Received: from donar.cv.nrao.edu (localhost.localdomain [127.0.0.1])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5HFv1g14218;
	Thu, 17 Jun 2004 11:57:01 -0400
Received: from polaris.cv.nrao.edu (polaris.cv.nrao.edu [192.33.115.101])
	by donar.cv.nrao.edu (8.11.6/8.11.6) with ESMTP id i5HFu6g14209
	for <aips2-developers at donar.cv.nrao.edu>; Thu, 17 Jun 2004 11:56:06 -0400
Received: from io.gb.nrao.edu (io.gb.nrao.edu [192.33.116.9])
	by polaris.cv.nrao.edu (8.12.8/8.12.8/smtp-gateway) with ESMTP id i5HFu6eL025106;
	Thu, 17 Jun 2004 11:56:06 -0400
Received: from webmail.nrao.edu (leo [192.33.116.10])
	by io.gb.nrao.edu (8.12.8/8.12.8) with SMTP id i5HFtxov003855;
	Thu, 17 Jun 2004 11:55:59 -0400
Received: from bgp01393641bgs.parads01.nm.comcast.net ([68.35.83.85])
        (SquirrelMail authenticated user ddebonis)
        by webmail.gb.nrao.edu with HTTP;
        Thu, 17 Jun 2004 09:55:59 -0600 (MDT)
Message-ID: <1062.68.35.83.85.1087487759.squirrel at webmail.gb.nrao.edu>
From: David DeBonis <ddebonis at nrao.edu>
Sender: aips2-developers-admin at donar.cv.nrao.edu
To: Ger van Diepen <diepen at astron.nl>
Cc: aips2-developers at nrao.edu, bglenden at nrao.edu
Subject: RE: [aips2-developers]Doxygen Change Proposal
Date: Thu, 17 Jun 2004 08:55:59 -0700
MIME-Version: 1.0
List-Help: <mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=help>
List-Subscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=subscribe>
List-Unsubscribe: <http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers>,<mailto:aips2-developers-request at listmgr.cv.nrao.edu?subject=unsubscribe>
X-BeenThere: aips2-developers at listmgr.cv.nrao.edu
X-Mailman-Version: aips2-developers at listmgr.cv.nrao.edu
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C45483.CE529943"
Status: RO
X-Status: 
X-Keywords:                 
X-UID: 8

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------_=_NextPart_001_01C45483.CE529943
Content-Type: text/plain;
	charset="iso-8859-1"

I'm sorry that I haven't been as responsive as I would have liked with
these comments, but I have been offline for most of this week due to the
Synthesis Summer School here in Socorro.

I don't feel that a total move away from cxx2html needs debating. 
Retaining ties to both doxygen AND cxx2html will cause unnecessary
maintenance complications.  Also, we are moving to doxygen to support a
commonly used code documenting format that is fully documented and
maintained independent of our distributions.  To maintain a mapping
simply
encourage the use of an unsupported documentation style that new
developers will need to learn for no reason.  I believe this would miss
the point of why we are moving to doxygen to begin with.

I have used doxygen for the past six years (since it was in beta) and
many
other developers are already fairly familiar with it.  It is similar to
JavaDoc which makes it familiar to anyone who has programmed in Java.
The
tags, though extensive, are comprehensive and as such support all that
cxx2html offers (as for the grouping based on physical location within
cxx2html, I disagree with this approach since this does not necessary
equate to logical groupings in all instances).

As mentioned in the proposal, the programming guide will be updated to
reflect the doxygen tagging convention.

David

> I proposed to use doxygen, but keep as much as possible the cxx2html
> tags because IMHO they are superior to the rather ad-hoc doxygen tags.
I
> think that in this way you mix the best of both worlds and you achieve
> that the AIPS++ developers don't have to learn a new documentation
> language.
> IMO another advantage is that (in principle) you protect the users
from
> the very extensive set of doxygen tags.
> Another advantage is that you can do the grouping in packages
> automatically, so moving a file does not require changing a
> documentation tag.
> Also note that doxygen supports the common html tags; probably they
> learned that people like to use such tags.
>
> I don't agree it means we have to reimplement cx22html; it means you
> have a simple and small Perl script to convert the tags. That script
has
> to be made anyway.
> Furthermore, if we have to start using /* */ for comments, we are
> partly back in the old C-world. I don't think anybody would like that.
> Certainly I won't.
>
> I agree with Wim's comments that someday you might want to switch to
> some other (better) tool.
> Converting from the doxygen tags seems more difficult to me than
> converting from the more limited and structured cxx2html tags.
>
> In development time it won't make any difference. The conversion
script
> always has to be made.
> In run-time it won't hardly make any difference. Running the script as
> an input-filter is fast enough.
>
> Cheers,
> - Ger
>
>
>>>> "Brian Glendenning" <bglenden at nrao.edu> 16-Jun-04 18:35 >>>
> If we are not going to change our tags, then what we are really doing
> is
> reimplementing cxx2html rather than using doxygen (which becomes then
> an
> implementation detail). On the other hand if we want to switch from
> cxx2html
> we should really switch rather than end up in some intermediate
> situation
> where we still have to maintain our own peculiar software, cannot just
> tell
> people to read the standard doxygen information, etc.
>
> Cheers,
> Brian
>
> _______________________________________________
> Aips2-developers mailing list
> Aips2-developers at listmgr.cv.nrao.edu
> http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers
>
> _______________________________________________
> Aips2-developers mailing list
> Aips2-developers at listmgr.cv.nrao.edu
> http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers
>

_______________________________________________
Aips2-developers mailing list
Aips2-developers at listmgr.cv.nrao.edu
http://listmgr.cv.nrao.edu/mailman/listinfo/aips2-developers

------_=_NextPart_001_01C45483.CE529943
Content-Type: text/html;
	charset="iso-8859-1"

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="MS Exchange Server version 5.5.2657.73">
<TITLE>RE: [aips2-developers]Doxygen Change Proposal</TITLE>
</HEAD>
<BODY>

<P><FONT SIZE=2>I'm sorry that I haven't been as responsive as I would have liked with</FONT>
<BR><FONT SIZE=2>these comments, but I have been offline for most of this week due to the</FONT>
<BR><FONT SIZE=2>Synthesis Summer School here in Socorro.</FONT>
</P>

I don't feel that a total move away from cxx2html needs debating. 
 Retaining ties to both doxygen AND cxx2html will cause unnecessary
 maintenance complications.&nbsp; Also, we are moving to doxygen to support a
 commonly used code documenting format that is fully documented and
 maintained independent of our distributions.&nbsp; To maintain a mapping simply
 encourage the use of an unsupported documentation style that new
 developers will need to learn for no reason.&nbsp; I believe this would miss
 the point of why we are moving to doxygen to beg