Tcl Source Code

View Ticket
Login
Ticket UUID: 3381085
Title: `make html` failure
Type: Bug Created on: 2011-07-28 15:52:31
Submitter: dgp Assigned to: dkf
Subsystem: 53. Configuration and Build Tools Severity: Minor
Priority: 2 Last modified: 2013-10-06 19:26:10
Status: Closed Closed by: dkf
Resolution: Fixed Closed on: 2013-10-06 19:26:10
Version: obsolete: 8.6b1.1
Description:
$ make html
...
scanning section Tk Library
..................can't read "head": no such variable
can't read "head": no such variable
    while executing
"man-puts "$head — $tail""
    (procedure "output-name" line 6)
    invoked from within
"output-name [join $names { }]"
    (procedure "output-directive" line 30)
    invoked from within
"output-directive $line"
    (procedure "make-man-pages" line 299)
    invoked from within
"make-man-pages $webdir  [list $tcltkdir/{$appdir}/doc/*.1 "$tcltkdesc Applications" UserCmd  "The interpreters which implement $cmdesc."]  [plus-base ..."
    ("try" body line 50)
make: *** [html] Error 1
User Comments:
dgp added on 2011-07-28 23:09:30:
This also looks wrong:

$ make html
using Tcl source directory tcl8.5
using Tk source directory tk8.5


I'm running `make html` in a trunk/rc directory
named "tcl" (with "tk" as a sibling) yet it's going
over into sibling dirs "tcl8.5" and "tk8.5" and
building their html docs instead?

dgp added on 2011-07-28 23:33:02:
Somehow the line 

.SS NAME

in tk/doc/CrtPhImgFmt.3 is getting processed
as though it were

.SH NAME

and the conventions of the NAME section
aren't met so the program throws an error.

Don't yet grok the whole $::manual(.) business
enough to see how that happens.

dgp added on 2011-07-28 23:35:17:
Ok, the two things are related.  The 8.5 docs
actually have ".SH NAME" and since we're picking
up the wrong data files we get the failure.

Not exactly robust if the tools with 8.6 fail on the
data from 8.5.

dgp added on 2011-07-29 00:08:51:
I can work around the problem with some 
symlinks tcl8.6 -> tcl and tk8.6 -> tk to give
the checkout directories names that work.

Of course, now the next time I try to `make html`
in the 8.5 directories, they will find 8.6 unless I remove
those symlinks, so a real fix would be better, but with
the workaround the urgency is reduced.

dkf added on 2011-07-29 15:30:19:
Re picking up the wrong version, that's a misdesign of the tool code that I've not done anything to change. When I'm building the docs I use:

  make html BUILD_HTML_FLAGS=--useversion= NATIVE_TCLSH=/tmp/tcl/bin/tclsh8.6

The value after --useversion (empty above; the = is significant) is really a pathname fragment that is used to find the tcl and tk documentation directories. (I hate it every time!)

dkf added on 2011-07-29 15:33:19:
Moreover, the 8.5 html builder should be used with the 8.5 docs, and the 8.6 builder with the 8.6 docs; those are the tested cases. (There were a lot of minor problems in the docs in 8.5, of which confusing misuse of section names was only one. It's all very very nasty.)

dkf added on 2013-10-06 19:26:10:

Added a new environment variable to unix/Makefile.in:

HTML_VERSION
The version of the documentation tree to build. If not specified, parses the name of the last component of the TOP_DIR makefile variable to get a sensible value.
You should be able to not specify the value as long as you're doing the build from within the source tree of the version you're trying to build. And if you are overriding it, it should be a lot easier to just override the version rather than dealing with the full whimsy of the build script's command line processing (which is Just Plain Weird).

You still need to have a native version of 8.6 about (and listed in NATIVE_TCL), as the build script uses try these days…