Two diffs to add paramater self-checking

Jay Ts jay at metran.cx
Tue Jul 16 02:42:32 GMT 2002


Gerald Carter wrote:
> 
> We try extremely hard, but sometime codes suffers from evolutionary 
> features where behavior mutates.  We rely on a lot of help from the 
> community to avoid this.  Hence my request for help.

Yes, I understand how difficult it can be to be busy programming,
and all the while keeping the official documentation perfectly
right-on.

But, I think that "help from the community" would best be in the
form of a way to submit reports of documentation errors or
insufficiencies, rather than actual updates.  With the exception
allowed for people who are actually studying the Samba source
code and actually know how things work. ;)

I don't know if this is agreeable to everyone, but my working 
model is to have the programmers explain their code at a technical
level (clear and complete, but not necessarily by any means Pulitzer
Prize-winning English or other human language), thus allowing admins
who can handle it read that documentation directly, while allowing
people who want to provide more user-friendly documentation (in the
form of HOWTOs, Usenet postings, emails, magazine articles, books, etc.
to have a decent starting place.  (Because I find I can't write the
user-friendly stuff while looking back and forth at C code!  It takes
too long, and is brain-melting.)

> Give a man a fish and he'll eat for a day.
> Teach a person to write SGML and he'll send 
> you patches. :-)

SGML doesn't look that bad ... not terribly different than
HTML anyway.  Later I might print out all the Samba docs
and submit diffs for the typos and other obvious inaccuracies
I've found.

The *hard* part is going to be translating Using Samba, from
Framemaker's buggy HTML output, to SGML.  I don't even want to
guess if this is even practicable.

Jay Ts
jay at jayts.cx




More information about the samba-technical mailing list