[docs] xmldocs - docelic modified 7 files

[Jon Jensen]

Davor,

Quite aside from all the excellent documentation work you've been doing, I
have been glad to see you making improvements to iccattut, and bringing it
up to date in a few areas. 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.

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.

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

> +ITL is a successor to <b>MML</b>, or <b>Minivend Markup Language</b>.

We don't need to mention MML or Minivend here at all. All the beginner 
needs to worry about is that he's using Interchange, and it has ITL.

> +(Up to version 5.x, Interchange was called Minivend).

It started being called Interchange at version 4.5, actually.

> +It is of vital
> +importance that you become familiar with this basic language and its
> +syntax. As ITL naturally progressed and the ammount of functionality
> +provided through it grew, it became more and more important to properly
> +learn the basics.
> +<a href="http://mark.stosberg.com/">Mark Stosberg</a>
> +once put up a theory that MML actually stood for <i>Mere Mortals Language</i>,
> +while you had to be <i>Information Technology Leader</i> to use ITL.
> +However, it's not as discouraging as it might seem - stick to our firm
> +guidance and you'll learn the basics without wasting your time.

I don't think we need to mention Mark Stosberg here, nor the cute 
acronyms. ITL isn't any more complicated than MML was. They're the same 
thing. And it's always been important to understand ITL, even in Minivend 
4.0.

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.

> +		As you learn and make sensible progress only when operating on
> +		the edge of your current abilities, I'll seriously take on my role
> +		of your temporary tutor and I'll be taking chances to give a
> +		bit broader context than the actual examples require.

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

> +		"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 ...

> +		Previous versions of this Guide used HTML tables for design and
> +		positioning. However, fundamental problems with using tables in design
> +		are widely known, alternatives are now available, we no longer neglect
> +		this Guide, and it is our obligation to condemn bad practice.
> +		Therefore, in November 2004., this Guide is switching to a proper
> +		and valid &glos-CSS; for elements of design; tables will be used
> +		only for numbers, kids!
> +		</para>
> +		<para>
> +		In essence, CSS is kept separately from your actual content
> +		page. Client's web browser loads both the content and CSS, and arranges
> +		the actual content display according to the CSS definition. We won't
> +		describe &glos-CSS; in more detail; it's only important to note that
> +		our CSS template will define a "3 column total, 1 fluid" layout,
> +		which <ulink url="http://www.glish.com/css/">glish.com/css/</ulink>
> +		rightfully considers to be the <emphasis>the Holy grail</emphasis>
> +		of CSS design.

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

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

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.

Let me know what you think.

Thanks,
Jon


--
Jon Jensen
End Point Corporation - http://www.endpoint.com/
Interchange Development Group - http://www.icdevgroup.org/
Software development with Interchange, Perl, PostgreSQL, Apache, Linux, ...