From: Michael S. <Mic...@gm...> - 2011-07-30 16:10:27
|
Hi all, just tried the build on OS X, worked fine, so the instructions seem up to date there. But some comments about the HTML docs: 1. Nice in general, but could use a bit more structuring to ease access. Maybe some grouping by topics in addition to the alphabetical listings. The ability to add some more structure/hierarchy to the docs is a major benefit of the HTML docs over the man pages, so it should be used if possible. 2. The copyrights listed on each page are sometimes a bit of overkill, do they really need to be placed like that on every page? In addition it would be nice if some of the copyright listings could be merged (for example: Copyright © 1992-1999 Karl Lehenbauer & Mark Diekhans Copyright © 1992-1999 Karl Lehenbauer and Mark Diekhans ) and probably similar for all the ActiveState related ones. 3. The tclsh page still lists the old 'exec tclsh' version for a start script, isn't the env tclsh one the new best way to do it? (like mentioned on http://wiki.tcl.tk/812 ) 4. Documenting lots of things under a heading of 'command' that are not commands 'Tcl commands' heading documents a lot of things that are not commands - global variables - tclsh/wish variables (which are in fact documented twice, on the tclsh/wish manpages and the global vars manpage, should be centralized) - same duplication for tcl_nowordchars, auto_path et. al. - Tcl syntax, re_syntax, filename - packages like 'dde', 'http', 'TclOO', 'msgcat', 'platform', 'tcltest', 'registry' - whole namespaces that are not ensembles: 'safe', - inconsistent naming 'tcl::tm' listed as tm , but tcl::prefix as tcl::prefix - env manpage does not document the special tm environment variables - try manpage and errorcode manpage are not linked nicely (only via see also tclvars) - transchan manpage is not linked from 'chan create' and lacks an example, it is also not really a command, more like an API/Interface, similar issues with refchan Tk's manpages have similar issues, documenting a lot of things under the heading of 'Tk commands' that are not commands: - cursors - colors - keysyms - options - tk_library - tk::mac and so on for itcl: - itcl, itclvars So maybe the headings should be changed? 5. Some missing links between man pages 'error' should have a link to the new try/throw 'proc' should probably mention 'apply' and maybe 'coroutine' Michael |