[docs] xmldocs - docelic modified 7 files

[Davor Ocelic]

> But I'm concerned that you're now
> overcomplicating the iccattut. Its original purpose was to be quite
> different from the other docs in that it didn't explain history, or all
> the options, or do anything more than give a brief walk through making a
> complete catalog from scratch.

Ah, sorry, I didn't remember I commited that to CVS. I changed my mind
already and was going to drop the whole introduction from index.html page
anyway.

I was just experimenting with stuff, and I probably checked it in
not thinking that anyone would go investigating what I did :)
(I change two computers so it's easier for me to check in the CVS than to 
drag current work with me on CDs).

So actually, the whole block of text you commented on wasn't actually
supposed that anyone sees it; I always experiment like this, then let it
consolidate in my mind to see which points are valid and which need to go.
But okay, I'll take the chance that we discuss some points.

> To start with, I don't think it should use TrackFile, or ImageDir, or
> SecureURL. If we use https, we have to worry more about webserver setup.  
> If we use ImageDir, we have to explain image tag rewriting, which would be
> best left for later. And why use TrackFile at all? I'd like to keep its 
> catalog.cfg as simple as possible, with very few directives.

Well, if we keep iccattut simple, then even after reading it people are
not able to take on harder stuff (let alone the foundation/standard catalog).

I had an idea of turning iccattut into a strongly-guided document that
shows all principles and logic behind constructing *usable* catalogs.
Furthermore, I had an idea of *slightly* raising the technical level - 
if the reader can't get his ImageDir properly - then chances are they
won't be able to follow the tutorial anyway - no matter how simple 
we make it. (And SecureURL is not a problem - I put the same value as
for VendURL in the example).

In my vision, iccattut would also be expanded in length, so that you
can look at the Standard demo after reading it and feel like you know
what's going on there.

Also, why I mention stuff like trackfile etc.? Because I believe in this
principle of expanding user's views by giving little implicit examples
(I waste no explanation on them, and it's still clear from the example
what the stuff does).
(To an extent - something like Programming Perl book authors - in the
very first chapters they mention some of deeper Perl stuff - not to
go explaining it, just to prepare reader's mindset for it once later).

> Next, the MML/ITL discussion has way too much detail for this tutorial:
> ....... 

Yes, this is all too silly, same comment as above applies; ignore
this whole thing...

> I'd like to see the ITL explanation be *extremely* brief. There's a whole 
> document, ictags, that explains this stuff in detail. For now, can't we 
> just get the user to *use* the tags simply, and follow our tutorial? That 
> was the point.

I wanted to move the description out of ictags to iccattut, because the
new "incarnation" of ictags are autogenerated reference indexes and
there's no place for prose there. And whenever you want to point
reader to this section, you can use like <olink doc=iccattut section=tags>.


Well, I am perfectly fine overriding my ideas with your decisions, so:

> Again, this is what I disagree with. I'd like this tutorial to remain 
> simple, and *not* expound on the many details.

Ok.

> > +		"Hey, there's nothing wrong with time and e-mail address display!
> > +		Most of so-called PHP "web shops" out there do just that" ;-)
> 
> I think we should avoid competitive "digs" like this ...

Ok.

> Any discussion of "proper" HTML and CSS is totally out of place here IMHO.

I have people asking me why iccattut uses tables for design, and also
questioning whether it's because IC can't use CSS. Ok.

> I'm feeling a bit protective of this document because I put so much work
> into making it simple, and I don't like to see it get bogged down and 
> complicated like all the other docs.

Well I thought we agreed (long time ago) to reduce the number of docs.
So I wanted to put everything that's related to basic stuff in iccattut.

> I'm considering ripping out any RPM 
> or Debian-specific stuff because that's made a mess of it too. A tarball 
> install in someone's home directory would make it more standard.

Nah, that is solved by the profiles thing.
If you build docs with "rh" profile, users only see values which apply to
.rpms (and the same analogy for .debs and tarballs).

> Davor, would you consider either trimming this back down to the simple
> whirlwind tutorial it was created to be, or else forking another document
> where you can make a more in-depth tutorial? I certainly don't think this
> was perfect before. One thing I would do differently now is I would not
> even cover Interchange's search specs now and would use SQL instead. But 
> that's a different topic -- further simplification.

I usually compare Interchange to similar "senior" free software projects
out there - Amanda, Postgres, some MTAs, GRASS, etc.. I have a vision
of how IC docs should look like to catch up with smaller and faster-moving
projects which draw a lot of attention and popularity to themselves. 
I also want to lower the "entry barrier" for the public. To be precise
actually, I want to keep the barrier high - but do that by
expecting users to do their share of preparation and homework, and not
by deliberately omitting details and keeping users no more familiar
with the software than they were before reading the documentation.


Well, I hope I clarified my original intent above. Read it, consider my
view, and reach the final decision. I'll simply agree with it
(even, of course, if it stays the same as stated in this mail).