[ic] Pee-Poor Documentation Rant

[Jim Balcom]

Another rant about the woeful documentation:::

I wanted to set up a Quote Of The Day (QOTD) on my main page using a file
that cron generates from 'fortune'.

I checked section 2.39 of the 'Interchange Tags Reference' and I came away
wondering what they said. This is VERY ambiguous and unhelpful
documentation. (It also refers to 'file' which is equally ambiguous.)

I would like to point out that this whole Interchange Tags Reference reminds
me of a DOS- based program that I had about 10 years ago. It consisted of 5
files and the program would act about like a Chinese Restaurant menu and
take one phrase from each column at random and make what was supposed to be
technically sound advice, which was actually nothing more than random
gibberish.

-----------------------------

Get this crap:

2.39. include
2.39.1 Summary

Parameters: file locale
Positional parameters in same order
Pass attribute hash as last to subroutine: no
Must pass named parameter interpolate=1 to cause interpolation
Invalidates cache: no
Called Routine:
ASP-like Perl call:
Not applicable

2.39.2 Description

Same as [file name] except interpolates for all interchange tags and
variables. Does NOT do locale translations.

---------------------

Does anyone know what this said????

I passed a parameter to interpolation last Wednesday and I didn't get off
the toilet until Friday!

They set the random number generators and selected phrases from each of 5
columns and put all of this gibberish together in the guise of
documentation.

As far as I am concerned this whole documentation is nothing more than a
pallitive on the part of Red Hat to say that they have provided
documentation for the product.

I am deeply sorry that Mike Heins had to sell out to Red Hat. The support
was far better when Mike had some control.

I can tell you, that after some experimentation I found that I can use the
phrase:

[include file="pages/qotd"]

and the contents of that file are displayed on my web page.

Now, why couldn't something like that have been put in the 'official'
documentation? It's really a very simple thing. Instead we have to deal with
major obfuscation!

-= Jim =-

----------------------------------------------------------------
Jim's Linux-Operated Underground Bomb Shelter

Tagline for Sunday, January 13, 2002 at 22:15 PM:
To get the point, rub a porcupine backwards.

----------------------------------------------------------------
This Linux System has been up 313 hours

My web page: http://www.idk-enterprises.com
----------------------------------------------------------------