ANNOUNCE: A bug fix in Zdoc
Vincent Wartelle
I fixed a bug in Zdoc: cross-references did not work for proc calls with a
left open bracket stuck to the proc name.
The bug has been fixed on October 1th, at 13:00 GMT. Then the bug fix has
been rewritten and published on October 3th, at 8:30 GMT.
URL is http://www.oklin.com/zdoc
V. Wartelle.
[[Send Tcl/Tk announcements to tcl-an...@mitchell.org
Send administrivia to tcl-announ...@mitchell.org
Announcements archived at http://groups.yahoo.com/group/tcl_announce/
The primary Tcl/Tk archive is ftp://ftp.neosoft.com/pub/tcl/ ]]
Petasis George
>
> I fixed a bug in Zdoc: cross-references did not work for proc calls with a
> left open bracket stuck to the proc name.
>
> The bug has been fixed on October 1th, at 13:00 GMT. Then the bug fix has
> been rewritten and published on October 3th, at 8:30 GMT.
>
> URL is http://www.oklin.com/zdoc
>
> V. Wartelle.
>
Actually I treid to use zdoc but I had quite a few problems, so I gave up...
What I tried was:
zdoc::init
catch {file delete --force zdoc}
## It an error for zdoc the output dir to not exist...
catch {file mkdir zdoc}
## Create a file list...
set SUBDIRS [list Viewers]
set FileList {}
foreach dir $SUBDIRS {
foreach file [glob ../$dir/*.tcl] {
if {[file isfile $file]} {
lappend FileList $file
}
}
}
zdoc::set_filelist $FileList
zdoc::set_source yes
zdoc::set_procsort alpha
puts $FileList
zdoc::run
I got too many errors about unknown functions, but that was solved by
running
the script from inside my application, where the correct auto_exec path is
set
and functions can get autoloaded whn needed.
But zdoc seems to have problems with path names. For example, in my tests
I tried to generate doc located in the directory ../Viewers/ from the
current
directory. It tried to generate files like ./zdoc/../Viewers/abc.html
and of course failed. I modified part of the original sources but the naming
scheme has to changed in many places, like links, etc.
My suggestion is that it has to be more careful regarding the naming of
output files. What if I want to generate docs about two directories that
contain
files with the same name, but with different content?
George
Vincent Wartelle
<snip>
> I got too many errors about unknown functions, but that was solved by
> running
> the script from inside my application, where the correct auto_exec path is
> set
> and functions can get autoloaded whn needed.
>
Yes, this is why there is the "zdoc::set_source no" option, to allow
the user to build the correct source context.
Another source of trouble are end braces not as first char of the line,
recognized as the end of the proc. Maybe I should allow just one blank
before proc end brace, do you agree ?
> But zdoc seems to have problems with path names. For example, in my tests
> I tried to generate doc located in the directory ../Viewers/ from the
> current
> directory. It tried to generate files like ./zdoc/../Viewers/abc.html
> and of course failed. I modified part of the original sources but the naming
> scheme has to changed in many places, like links, etc.
>
> My suggestion is that it has to be more careful regarding the naming of
> output files. What if I want to generate docs about two directories that
> contain
> files with the same name, but with different content?
>
> George
Sorry about this bug, your are right. My personal use of zdoc is to document
a project whose all files are in a single directory.
May I suggest as a solution that I change the relative pathname to a prefix
of the doc file ? For example, changing ".." to "_" and "/" to "."
would generate files like:
./zdoc/_.Viewers.abc.tcl.html
for the corresponding
../Viewers/abc.tcl
and of course
./zdoc/_.Other.abc.tcl.html
for
../Other/abc.tcl
If you have better ideas, please tell. Remember I need chars valid under Unix
and Windows.
Vincent.
Petasis George
>
> <snip>
> > I got too many errors about unknown functions, but that was solved by
> > running
> > the script from inside my application, where the correct auto_exec path is
> > set
> > and functions can get autoloaded whn needed.
> >
>
> Yes, this is why there is the "zdoc::set_source no" option, to allow
> the user to build the correct source context.
>
> Another source of trouble are end braces not as first char of the line,
> recognized as the end of the proc. Maybe I should allow just one blank
> before proc end brace, do you agree ?
I didn't have this problem yet, as all my procs have their end braces as the
first
character in the line. Perhaps white space exists when I code thinks like:
namespace eval x {
proc y {} {
}
}
Actually, _.Other.abc.tcl.html may be "programmatistically" valid under
windows, but you cannot rename it under windows explorer :-)
My suggestion is simpler:
Just use the filename and its parent dir: ../Viewers/abc.tcl ->
Viewers_abc_tcl.htm
BUT before opening the file, see if it exists (file exists ...).
If it exists, simply append a number:
Viewers_abc_tcl_1.htm
Viewers_abc_tcl_2.htm
and so on...
Using the parent directory should give some freedom, as it may be rare to
find
to directories in an app that have the same name. And with the check you
ensure
that even if it happens, the generated html files are unique.
Also another point: In the generated html index, can all tables have the
same width?
I find it a little frustrating to have to constantly adjust the
scrollbars...
Also, can you place the "generated with zdoc" at the end of the page?
I think it is more common to be at the end...
Thanks,
George