[ic] Re: [interchange-cvs] interchange - docelic modified 5 files

[Davor Ocelic]

On Wed, 29 Mar 2006 14:34:10 +0200
Andreas Grau <agrau at esquat.com> wrote:

> On Wed, 29 Mar 2006 13:27:00 +0200
> Davor Ocelic <docelic at mail.inet.hr> wrote:
> 
> > On Wed, 29 Mar 2006 13:12:33 +0200
> > Davor Ocelic <docelic at mail.inet.hr> wrote:
> > 
> > > On Wed, 29 Mar 2006 05:43:19 +0200
> > > Andreas Grau <agrau at esquat.com> wrote:
> > > 
> > > > > --- qb_safe.filter	8 Nov 2005 18:14:32 -0000	1.6
> > > > > +++ qb_safe.filter	27 Mar 2006 22:21:13 -0000	1.7
> > > > > @@ -1,11 +1,7 @@
> > > > >  # Copyright 2002-2005 Interchange Development Group (http://www.icdevgroup.org/)
> > > > >  # Copyright 1996-2002 Red Hat, Inc.
> > > > >  # Licensed under the GNU GPL v2. See file LICENSE for details.
> > > > > -# $Id: qb_safe.filter,v 1.6 2005/11/08 18:14:32 jon Exp $
> > > > > -
> > > > > -# QuickBooks Safe: make data safe for quickbooks
> > > > > -# QB will crash at the drop of a hat, so don't forget to remove 
> > > > > -# any unfriendly characters.
> > > > > +# $Id: qb_safe.filter,v 1.7 2006/03/27 22:21:13 docelic Exp $
> > > > >  
> > > > 
> > > > What's wrong with the comment ?
> > 
> > Oh yes, and another point is: we will be having documentation available
> > in manpages format. So you will just say "man qb_safe", without the
> > need for opening web browsers or PDF viewers.
> 
> This is good news. When will this be ?

It already is. Just not in default build. (And spare me the trouble of
replying to "So when will it be in default build?")

> Other than that, and I don't want to be a pain in the neck (although I
> probably am), my questions remains open: _For which reason_ do you take
> the comments out. You could *copy* them, for example. Or you could even
> *add* to them. Are you going to delete *all* inline documentation ?
> I am meaning not WHY (because there the answer is clear: it has been
> decided), I am asking "for what purpose".

Dear Andreas. I kindly redirect you to the following sentence from my
previous email:

"At least one problem with comments in files is that, when you 
are looking at the documentation in xmldocs, you first read
the information in the proper place (under DESCRIPTION or NOTES
section), and then when you scroll down to see tag source code,
you see it in there again."

If that didn't answer your question, well....

Another problem is that the same information in two places is 
guaranteed to go out of date.

> There once was a time, when generating documentation from inline
> comments was state of the art, because one found that programmers, who
> are known to notoriously avoid writing documentation, prefer to
> document as they code, instead of keeping two different files in
> sync.

Go play elsewhere.

> I am curious to understand the reasoning what benefit tearing all apart
> may bring. And how you intend to keep the docs in sync.

"Tearing all apart" ? Let me remind you and others of your previous 
statements:

  > Take an unsupportive mailing list plus zero docs, and you come ....

You obviously like to give things imaginary proportions, and then work
the story from that point on.