Re: [Modeling-users] Raw Qualifiers

[Yannick G. <ygi...@yg...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wednesday 16 July 2003 08:13, Sebastien Bigaret wrote:
>   Thanks a lot Yannick for this nice clarification. I'll probably
> include your message as-is in the documentation until I find some time
> to rewrite it

No problem.  And as I asked in private why LaTex instead of DocBook ?
DocBook is a really simple mark up with implied support for unicode
since it's XML.  30 different tags max in a regular document.  KDE,
Gnome, Python and Linux are all moving to DocBook.  I would have put
it the mark up myself but this LaTex thing is beyond my mere mortal
capabilities.

 ; )

> (I already have quite a bunch of doc. to write, and you
> now know what happens when I have too much doc. to write: I had
> features, which implies even more doc. to write, but well, that's my
> delaying tactics ;).

Everyone needs a bit of entertainment !=20

 : D

>     Little disgression: the very reason why I made the QualifierParser,
>     then documented it only, is historically bound to the somewhat
>     complex API for fetching objects; before we get the current
>     ec.fetch(), fetching implied qualifierWithQualifierFormat,
>     FetchSpecification and ec.objectsWithFetchSpecification(). People
>     were not finding it that handy/friendly, imagine their groans if I
>     had put on top of that step-by-step instructions to build
>     qualifiers!

They would have hunt you down to poke your eyes !  Well, I would have
done just that...  ; )

> > So I hope this will help you all to get the best out of the framework.
> > The best source of doc is not the doc, the doc may get a bit out of
> > synch.  Dive into those sources up to the unit tests.  S=E9bastien wo=
rks
> > hard to get all of those working all the time so you're sure to find =
a
> > lot of working example there.
>
> Writing docs in very time-consuming, and writing *good* doc. is more
> then that ;) Hopefully it's not that bad...
>
> About unittests: yes, I maintain then very strictly. Mostly every bug
> gets its unittests before being fixed (even if I rarely expose them in
> patches), new features get unittests before I start coding, so you can
> definitely rely on them.

No the doc is not that bad.  This is just a reminder that code is
meant to be read by both human and computers.  Furthermore, a good
programming language will be more expressive that english.

How many words to explain "(%s)" % ", ".join(map(str, aList)) ?  But
it's still quite readable.  When you can't find it in the doc, or when
the doc is unclear, do a quick grep.  It might be obvious in Python.

The case of the unit tests is really special.  The fact that those are
your quality assurance kit means that they are guaranteed to work.
There is in those tests an amazing amount of working example and we need
just that : a picture.  I think that the doc should mention them, they
are more valuable than you think.

Regards,=20

- --=20
Yannick Gingras
Coder for OBB : Out Biconcave Beingness
http://OpenBeatBox.org
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE/FNYlrhy5Fqn/MRARAgTBAJ9jc+uJnMBQoO7xUb5JoQilss6NEwCfUo8O
dY3FlKFQwdqOSCAj7lvBHrg=3D
=3DftmW
-----END PGP SIGNATURE-----