Tcl Source Code

View Ticket
Login
Ticket UUID: 1e10b170233c0f147945ef0ab0b295237807faf1
Title: `make html` How should it work?
Type: Bug Created on: 2021-06-18 18:19:51
Submitter: dgp Assigned to: nobody
Subsystem: - New Builtin Commands Severity: Minor
Priority: 5 Medium Last modified: 2021-06-18 18:28:24
Status: Open Closed by: nobody
Resolution: None Closed on:
Version: 8.7*
Description:
The html documentation building code in tools/tcltk-man2html* has diverged
between the Tcl 8.6 and Tcl 8.7 branches in ways that have disrupted the
use of `make html` to create the documentation distributions for Tcl/Tk 8.7a
releases.

This ticket is opened to maybe lay down some information about what changed,
why, how the `make html` target is used, and how changes have broken those
uses.
User Comments:
dgp added on 2021-06-18 18:28:24:
From my perspective, I use only the `make html` target, and I use it
only to create the documentation distribution.  My habit is to have
a top level directory with the same name it has in the release.
In the latest release, that was a directory named "tcl8.7a5".  I want
`make html` to build docs for both Tcl and a matching release of Tk
under a directory named `tk8.7a5`.  I do my distribution making operating
in the "unix" subdirectory.

When I came to make the latest distribution,
the `make html` target failed to do what I needed, and the next 5 or so
attempts to feed it a set of command line arguments to make it behave
also failed.  The command line arguments are poorly (sometimes falsely)
semi-documented by the -help message.  It is not clear what knobs control
what consequences.  I see also that in the finished product, the presented
css style is now changed, and the filenames have changed from "contents.htm"
to "index.htm" if not more layout changes (why?).

I don't mind adapting to new habits so long as I have a prayer of
understanding what to do, and we don't get into a cycle of changing
things every time with little apparent need.