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

[Stefan Hornburg]

Andreas Grau 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 ?

Obviously when it is ready.

> 
> 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 ?

Yes, he is going to do that. Any duplication is a bad thing in terms of
programming.

> 
> I am meaning not WHY (because there the answer is clear: it has been
> decided), I am asking "for what purpose".
> 
> 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.

Better to actually do something in a consistent way then pretend to be "state of
art". I'm pretty sure that the Interchange developers who already spent a
substantial amount of time with Interchange documentation understand and
support Davor's documentation project.

The documentation effort definitely benefits from submissions and input,
so don't get me wrong.

Bye
	Racke


-- 
LinuXia Systems => http://www.linuxia.de/
Expert Interchange Consulting and System Administration
ICDEVGROUP => http://www.icdevgroup.org/
Interchange Development Team