#644 Allow tcltk-man2html to accept package directory

open
5
2013-01-07
2013-01-07
Twylite
No

tcltk-man2html.tcl is used to build HTML documentation on Windows and other platforms. It attempts to include documentation for extensions/packages, but is limited to find packages under $tcldir/pkgs/ .

When building from repository checkouts (rather than the official Tcl source distribution) or building non-TEA compliant packages it is (in this developer's opinion) convenient to locate extensions adjacent to rather than under $tcldir.

To support this I suggest a command line option "--pkgdir" that can specify the directory under which package sources can be found, as an absolute or relative (to pwd) path. The default if "--pkgdir" is omitted is $tcldir/pkgs, retaining backwards compatibility.

Implementation is in the Fossil repo in branch frq-(this frq).

Discussion

  • It probably ought to have something in to better handle packages whose names aren't in the dir-name-prefix/package-name map file.

     
    • assigned_to: hobbs --> dkf
     
  • Twylite
    Twylite
    2013-01-07

    I'm open to suggestions. There is already a fallback case to use the directory name.

    Two things I can think of are:
    (1) Look under --pkgdir for package.list.txt.
    (2) Fall back to the package name from AC_INIT in configure.in (if available) before the directory name.

    ?

     
  • I'm also open to suggestions, but it's broken out into package.list.txt to make it easier to maintain. Eventually, I might move the other special case stuff into a (different) separate file too, but that's a "if/when required" thing. :-)

     
  • The main thing is that whatever you do, test that it works. :-) One of the main reasons why the HTML build is now in fairly good health is that we (well, mostly me but also dgp) put quite a bit of effort into ensuring that it actually produces sane output.

     
  • Twylite
    Twylite
    2013-01-07

    We could use a DESCRIPTION.txt file (TIP #55, http://www.tcl.tk/cgi-bin/tct/tip/55.html\) in the root dir of the package as the authoritative source of information ... not that I've ever seen such a file in a package, but in theory it solves the problem ;)