ANN: WINHELP version of Tcl docs available
Joe English
A copy of the Tcl core documentation in Windows Help format
is now available here:
<URL: http://tmml.sourceforge.net/tcl-help.zip >
The zip archive contains two files, tclman.hlp and tclman.cnt;
be sure to extract both files, the Windows Help viewer needs both of them.
The help file was generated from the current CVS version
of the Tcl man pages via TMML and RATFINK/Cost. There are still a
few kinks in the conversion process, but once I get these
worked out I'll add the Tk docs as well.
Enjoy!
--Joe English
David Gravereaux
Thank you, Joe! It looks good and different. The non-scrolling header could
use some color and maybe an icon. And maybe some link buttons to jump to URLs
like http://www.tcl.tk, et. al.
I like how the keywords bring up a search list.
If you get a chance, have a look at the winhelp target in makefile.vc for Tk and
how you can install an addition helpfile into another's contents file with
`exec winhlp32 -g ...`
Do your conversion utilities need a lot of dependencies? Are these the right
links? Do I have everything?
http://prdownloads.sourceforge.net/tclxml/tclxml-2.1theta.zip
http://www.flightlab.com/~joe/downloads/cost-2.3-2002-04-26.exe
http://www.flightlab.com/cost/ratfink/ratfink-0.9.tar.gz
Does
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tmml/tmml/tools/tmml-winhelp.tcl?rev=1.3&content-type=text/vnd.viewcvs-markup
actually call the help compiler, or does this just do the rtf?
--
David Gravereaux <davy...@pobox.com>
[species: human; planet: earth,milkyway,alpha sector]
Please be aware of the 7.5 year ping times when placing a call from alpha centari
Joe English
>
>Thank you, Joe! It looks good and different. The non-scrolling header could
>use some color and maybe an icon. And maybe some link buttons to jump to URLs
>like http://www.tcl.tk, et. al.
OK. I was also considering putting jumps to the section
headings in the top banner, a la the HTML rendition.
What would be a good color scheme? ActiveState beige for the
banner maybe?
>If you get a chance, have a look at the winhelp target in makefile.vc for Tk an
>how you can install an addition helpfile into another's contents file with
> `exec winhlp32 -g ...`
Ah, that's been enhanced since I last looked at it.
But doesn't 'winhlp32 -g' just generate a .GID file?
I thought those were host-specific (since they embed
absolute pathnames into the index).
>Do your conversion utilities need a lot of dependencies?
Quite a few...
> Are these the right links? Do I have everything?
Depends on what you want to do -- you might also need
to get the current TMML distribution from SourceForge CVS.
Check out the 'coredocs' module as well if you want to process
the Tcl/Tk manpages (but note that this is still somewhat broken.)
>http://prdownloads.sourceforge.net/tclxml/tclxml-2.1theta.zip
TclXML is also included in the ActiveTcl distribution, which is
what I used.
The NROFF-to-TMML up-converter uses TclDOM, which is also
in ActiveTcl, but only the pure-Tcl version, which is *really*
*really* slow. You'll probably want to build dom::c and
use that.
>http://www.flightlab.com/~joe/downloads/cost-2.3-2002-04-26.exe
>http://www.flightlab.com/cost/ratfink/ratfink-0.9.tar.gz
RATFINK is now bundled with Cost, so you don't need to
download it separately. However, the 26 April 2002 version
of Cost won't work; I'm in the middle of overhauling RATFINK
and the TMML-WINHELP converter needs the development version.
I'll have a new snapshot out early next week.
>Does [...]tmml-winhelp.tcl[...] actually call the help compiler,
> or does this just do the rtf?
That just builds the .RTF and .CNT files. At present I'm
maintaining the .HPJ file by hand and calling the help
compiler from a makefile, but plan to automate that
part as well.
--Joe English
David Gravereaux
>David Gravereaux wrote:
>>
>>Thank you, Joe! It looks good and different. The non-scrolling header could
>>use some color and maybe an icon. And maybe some link buttons to jump to URLs
>>like http://www.tcl.tk, et. al.
>
>OK. I was also considering putting jumps to the section
>headings in the top banner, a la the HTML rendition.
>
>What would be a good color scheme? ActiveState beige for the
>banner maybe?
I was playing with bright yellow and the feather icon for Tcl and bright orange
and the lantern icon for Tk. I have Itcl at fluorescent green with the toaster
icon :) Colors are set in the .hpj and you can set an icon in the RTF somehow.
I added it to tools/man2help.tcl, but have since forgotten the details. This
isn't set in stone or anything. I'm just playing around. Black and white looks
too drab for me.
Is there a data entity in TMML for project icons and possibly color schemes? I
saw the homepage link, but I'm not much for reading dtds in raw form. I should
read the docs :)
>>If you get a chance, have a look at the winhelp target in makefile.vc for Tk an
>>how you can install an addition helpfile into another's contents file with
>> `exec winhlp32 -g ...`
>
>Ah, that's been enhanced since I last looked at it.
>But doesn't 'winhlp32 -g' just generate a .GID file?
>I thought those were host-specific (since they embed
>absolute pathnames into the index).
Yes, that's why its part of the install target. It barely works, but does,
sorta, in it's current form. When installing a new tcl84.cnt it wipes out all
the other :Include lines. Maybe having a top-level .cnt that just has :Include
lines would be a better way to go?
>>Do your conversion utilities need a lot of dependencies?
>
>Quite a few...
Could I help getting this all together for a single prowrap or freewrap app?
Jeffrey Hobbs
...
> >OK. I was also considering putting jumps to the section
> >headings in the top banner, a la the HTML rendition.
> >
> >What would be a good color scheme?
>
> and the lantern icon for Tk. I have Itcl at fluorescent green with the toaster
Ack, you've got to be kidding. Muted colors please. It makes it
hard on the eyes when it is a riot of colors like that. There are
some pages on the net that provide advice on good color combinations
for onscreen reading.
--
Jeff Hobbs The Tcl Guy
Senior Developer http://www.ActiveState.com/
Tcl Support and Productivity Solutions
Joe English
[ By the way, the Windows Help version has been updated; it now includes
the Tk reference manual too: <URL: http://tmml.sf.net/tcl-help.zip > ]
David Gravereaux wrote:
>Joe English wrote:
>>What would be a good color scheme? ActiveState beige for the
>>banner maybe?
>
>I was playing with bright yellow and the feather icon for Tcl and bright orange
>and the lantern icon for Tk. I have Itcl at fluorescent green with the toaster
>icon :)
I've decided to go with ActiveState beige instead :-)
>Is there a data entity in TMML for project icons and possibly color schemes?
No, since that's highly rendition-specific. That sort of thing
could put in a processing instruction though.
>Could I help getting this all together for a single prowrap or freewrap app?
That would be great, thanks!
--Joe English
Donal K. Fellows
> A copy of the Tcl core documentation in Windows Help format
> is now available here:
> <URL: http://tmml.sourceforge.net/tcl-help.zip >
You do realize that this is cooler than a beach holiday in Adélieland?
Donal.
--
Donal K. Fellows http://www.cs.man.ac.uk/~fellowsd/ fell...@cs.man.ac.uk
-- Short attention span since- ooh! Shiny thing on the floor!
-- Chad R. Orzel <orz...@earthlink.net>
Chris Nelson
>
> Joe English wrote:
> > A copy of the Tcl core documentation in Windows Help format
> > is now available here:
> > <URL: http://tmml.sourceforge.net/tcl-help.zip >
>
> You do realize that this is cooler than a beach holiday in Adélieland?
I've never been to Adélieland, but it's pretty cool. ;-)
Is there anyway to tell what version of Tcl this file describes?
Chris
--
Rens-se-LEER is a county. RENS-se-ler is a city. R-P-I is a school!
Joe English
>> Joe English wrote:
>> > A copy of the Tcl core documentation in Windows Help format
>> > is now available here:
>> > <URL: http://tmml.sourceforge.net/tcl-help.zip >
>>
>> You do realize that this is cooler than a beach holiday in Adélieland?
Thanks :-)
Chris Nelson wrote:
>Is there anyway to tell what version of Tcl this file describes?
It's based on the current (6 May 2002) CVS HEAD from SourceForge,
so it doesn't correspond to any formal release. Once I get a
couple more bugs fixed in the translator, I can build a version based
on the 8.3.4 release.
--Joe English
Darren New
> >> You do realize that this is cooler than a beach holiday in Adélieland?
>
> Thanks :-)
Yes, very nifty, very nice. Excellent TOC and such.
It might help readability to put the Tcl code into boxes (rather than
just separated by horizontal lines) or not indent it or something like
that. In the middle of a sentence, it's fairly hard to follow something
like
If the user types
-------------------------------
puts $hello
-------------------------------
then the output of
-------------------------------
exec this that
-------------------------------
will be mumble.
Due in part to all the font changes, it's rather difficult to follow the
text. Maybe just getting rid of the HRs would help. Something to look
at. Just a thought.
--
Darren New
San Diego, CA, USA (PST). Cryptokeys on demand.
The 90/10 rule of toothpaste: the last 10% of
the tube lasts as long as the first 90%.
Joe English
>
>It might help readability to put the Tcl code into boxes (rather than
>just separated by horizontal lines) or not indent it or something like
>that.
Alas, Winhelp doesn't support boxes, only rules.
I tried it without the horizontal lines at first and found that
harder to read. I'll try losing the indentation next.
Thanks for the feedback.
--Joe English
Darren New
> Alas, Winhelp doesn't support boxes, only rules.
I was afraid of that. Usually it's done with <table> tags having only
one row and column, in HTML.
> I tried it without the horizontal lines at first and found that
> harder to read. I'll try losing the indentation next.
Actually, maybe just inlining it but putting it in a different color,
like dark blue, would work better. The really confusing part is when you
lose the indent afterwards. Like if you look on the page for [file] in
the sub-option of [file join], at least on my machine it looks really
funny, because the indent gets completely lost after the example. (This
is something Netscape 4.x screws up too, but I'm not sure what's going
on with winhelp.) [file dirname] is also pretty confusing, but might be
much clearer if it just used a different color. (Don't know if you can
distinguish those cases, tho.)
lvi...@yahoo.com
Perhaps some day someone will consider building a Tcl/Tk application to
provide equivalent functionality - just think of a scripted document,
containing the code and the help pages, and tclkit's that could be built
for nearly any place that tcl runs...
--
Support Internet Radio <URL: http://saveinternetradio.org/ >
<URL: mailto:lvi...@cas.org> <URL: http://www.purl.org/NET/lvirden/>
Even if explicitly stated to the contrary, nothing in this posting
should be construed as representing my employer's opinions.
Jean-Claude Wippler
> Perhaps some day someone will consider building a Tcl/Tk application to
> provide equivalent functionality - just think of a scripted document,
> containing the code and the help pages, and tclkit's that could be built
> for nearly any place that tcl runs...
Isn't that what has been around for quite some time now, a wrapped set
of html pages plus TkHtml (for Linux, Win32, and Solaris currently)?
There are several documentation sets, all available from:
http://www.equi4.com/pub/dok/
As well as from Steve Landers' new scripted document archive:
http://mini.net/sdarchive/
(See the "Documentation" section - "dok" packs are trivial to create)
It's based on the "hv" script, with small additions to go back one page
and to the "home" page (it could certainly use a few more conveniences,
such as keyboard shortcuts). Adding search capability, as in the wiki,
might also be a very useful improvement IMO. But even as is, I use it
on an almost daily basis.
-jcw
Joe English
>Joe English wrote:
>> I tried it without the horizontal lines at first and found that
>> harder to read. I'll try losing the indentation next.
>
>Actually, maybe just inlining it but putting it in a different color,
>like dark blue, would work better.
WINHELP doesn't have much support for color either; you
can specify the background color of the banner and main areas,
and the foreground color of links, but that's about it.
> The really confusing part is when you lose the indent afterwards.
That one is a (known) bug in my translator. Working on that...
> Like if you look on the page for [file] in
>the sub-option of [file join], at least on my machine it looks really
>funny, because the indent gets completely lost after the example. (This
>is something Netscape 4.x screws up too,
Which version of the man pages?
Does <URL: http://tmml.sf.net/doc/tcl/file.html > exhibit this behaviour?
(It doesn't for me under Netscape 4.74.)
Hm... file.n has some inconsistencies in the nroff markup, part
of the problem may come from that.
--Joe English
Darren New
> WINHELP doesn't have much support for color either; you
> can specify the background color of the banner and main areas,
> and the foreground color of links, but that's about it.
Gak. What a POS. :-)
> Which version of the man pages?
> Does <URL: http://tmml.sf.net/doc/tcl/file.html > exhibit this behaviour?
> (It doesn't for me under Netscape 4.74.)
Me neither, 4.77, but for [file normalize]
It was just other HTML-based manual pages from other projects that
didn't quite do the right thing. I'm not sure why. Never really persued
it.
Chris Nelson
> ...
> > Is there anyway to tell what version of Tcl this file describes?
>
> It's based on the current (6 May 2002) CVS HEAD from SourceForge,
> so it doesn't correspond to any formal release. Once I get a
> couple more bugs fixed in the translator, I can build a version based
> on the 8.3.4 release.
It's not clear to me if that release will then tell you it's for 8.3.4.
My problem would be having multiple help files and/or multiple releases
on my system and not knowing, as I looked at a help entry, what version
of Tcl it corresponded to. Maybe you could put the version in the
header?
David Gravereaux
>Joe English wrote:
>> WINHELP doesn't have much support for color either; you
>> can specify the background color of the banner and main areas,
>> and the foreground color of links, but that's about it.
>
>Gak. What a POS. :-)
Hey Joe,
Where's the rtf format/usage used for winhelp documented? "Help Workshop" is a
bit klunky to me with "Help RTF token Reference" all lumped on one page. Can
table colors be specified? I can't make much sense of the tags.
Joe English
>
>Where's the rtf format/usage used for winhelp documented? "Help Workshop" is a
>bit klunky to me with "Help RTF token Reference" all lumped on one page.
As far as I know, that's the only place where it's documented
(and that, in addition to being ill-organized, is incomplete).
The full RTF specification is available here:
<URL: ftp://ftp.microsoft.com/Softlib/mslfiles/gc0165.exe >
That's a self-extracting Word document. Ick. Newer versions
are available in MS HTML on the MSDN Web site; google for
'RTF specification' (I'd post a link here but it will probably
have moved again by the time you read this :-)
> Can table colors be specified?
As far as I know, no.
> I can't make much sense of the tags.
Yeah, the HCW docs make little sense until you've read the
base RTF spec (at least the first couple of sections).
After you've read the base RTF spec, you'll see that
the tags don't make any sense at all. RTF, especially
WINHELP-style RTF, is the most astonishingly awful file
format I have ever seen.
--Joe English
lvi...@yahoo.com
According to Jean-Claude Wippler <j...@equi4.com>:
:In article <abb7lf$4kc$1...@srv38.cas.org>, lvi...@yahoo.com wrote:
:
:> Perhaps some day someone will consider building a Tcl/Tk application to
:> provide equivalent functionality - just think of a scripted document,
:> containing the code and the help pages, and tclkit's that could be built
:> for nearly any place that tcl runs...
:
:Isn't that what has been around for quite some time now, a wrapped set
:of html pages plus TkHtml (for Linux, Win32, and Solaris currently)?
I don't know - I don't currently have access to a Windows system where
I can try out the WinHelp to see what it does besides display the
documentation.
Does the above scripted doc include any searching capability?
Joe English
A new copy of the Tcl/Tk reference manuals in WINHELP format
has been uploaded:
<URL: http://tmml.sourceforge.net/tcl-help.zip >
The help file was generated from the current (16 May 2002)
man pages in SF CVS. This version fixes most of the
issues raised on comp.lang.tcl; thanks to everyone
for the feedback.
(The indentation -- which was surprisingly difficult to fix --
is still not quite right, but I'm calling it good enough :-)
--Joe English