zic.8 in html

[Oscar van Vlijmen]

>> Therefore and once again, I converted the latest version of the zic.8 file
>> to html.
> Did you generate the HTML automatically?  If so, I'd rather put the
> automated procedure into the makefile.  If not, then I'm a bit
> dubious.  I'd rather not maintain two forms of the documentation by
> hand.  In my experience, HTML is not a particularly good way to
> maintain computer documentation.  I'd far rather use texinfo, but even
> man pages are better than HTML.
> Ideally the automated procedure, whatever it is, would generate XHTML
> 1.1, which is the latest version of HTML.  (Hmm, I see that
> tz-link.htm and tz-art.htm specify XHTML 1.0; time to upgrade.)


Sorry that I am again (cf. my emails dated 2000-04-19, 2002-04-07,
2003-10-09) not able to make this point clear.
Allow me to try to explain the situation again.

If the maintainers of the TZ distribution believe that they should only
support the platforms the TZ software is targeted at then: don't do no
nothing! Just leave all documentation as is.

The reality is however that once in a while some developer is trying to use
the TZ database files for developing a completely different application.
Don't believe it, but it is true: not everybody has a Unix/Linux operating
system. Not everybody has a C compiler (Makefile!). Not everybody has a
groff/troff reader (zic.8!). Not everybody has a Texinfo, DocBook or
linuxdoc-sgml reader. Not everybody has an XHTML 1.1 capable browser.

At this moment in time there are two viable options for producing
documentation for other platforms than the TZ software is aimed at:
- text only, iso-8859-1 encoding, file name ending in .txt
- html 4.01, iso-8859-1 encoding, file name ending in .htm(l)
Whatever fancy software you might have, whatever software a 'regular' TZ
user is able to run, at the moment only text-only and html 4 are truly
platform independent.
Why not something fancy?
Why not according to the latest 'standards'?
The answer is simple: not all computer platforms are alike and most software
firms are not willing to conform to the latest standards.

So: if TZ is solely targeted to and supported for POSIX-compliant hosts,
including BSD, HP, Linux, Network Appliance, SCO, SGI, and Sun, then don't
change anything in the documentation.
Just ignore others and let them try to find out for themselves what is going
on.

If the TZ maintainers are willing to offer a small service to users of the
TZ database files on other platforms, please consider to offer platform
independent documentation in text-only or html 4 format.

The least amount of effort would be: put an extra file in the distribution,
namely zic.8 converted to text or html.
>From Paul Eggert, 2000-04-20:
' "groff -Thtml -man zic.8" would have done it automatically '

Since it is to a non-target user not clear why ever he/she should read zic.8
or zic.html, something of this nature could be mentioned in the file
"README", like:

More information about the files in this distribution and their backgrounds
can be read in the documentation file "Theory".
The file "zic.html" describes, amongst others, the format of the TZ database
files in the tzdata directory.

The latter sentence could be repeated as a new item in the file "Theory"
after:
"Points of interest to folks with other systems:"



> I'd rather not maintain two forms of the documentation by hand.
Why not? The files "Theory" and "zic.8" hardly ever change. It would be not
too difficult to make once every 3 years or so a minor change in 2 files at
once (zic.8, zic.html), not even by hand!

> In my experience, HTML is not a particularly good way to
> maintain computer documentation.
It is a very useful way on other computer platforms like Windows and
Macintosh. At any rate html 4 (yes: 4.01) without too much css is very
platform independent and compatible. As is text-only.

> ... computer documentation.  I'd far rather use texinfo, but even
> man pages are better than HTML.
Not compatible with other platforms.

> Did you generate the [zic8.html] HTML automatically?
By hand, in order to keep most of the formatting in the zic.8 file, and
because I have no groff converter/reader!


Oscar van Vlijmen
2003-10-12