Menu
▾
▴
Re: [naviserver-devel] Cleanup progress report
|
From: Georg L. <jor...@ma...> - 2024-12-07 22:06:53
|
Hello Gustaf, Your dedication is impressive, thank you! FWIW: At some moment Flighaware issued a bounty on reactivating the TclPro Debugger. I found an email from Steve Bennet from 3rd of July of 2017, when he announces that they made it available on github in the repo flightaware/TclProDebug. That's all I can add. I don't use debuggers a lot and have not used TclProDebug. Best Regards, Georg On 12/4/24 13:57, Gustaf Neumann (sslmail) wrote: > Dear fellow NaviServer users and developers, > > this is a progress report on the cleanup. Points 1-5 are done, no all > the parameters implemented are also documented in the manual pages, > the last days I fixed the documentation of 330 API calls, where the > implementation and the documentation differed. > >> > 1) all commands tested in the regression test should be documented >> > 2) all documented commands should be tested (at least syntax-tested) >> > 3) all implemented commands should be tested >> > 4) the parameters of the implemented commands should be >> documented and vice versa. >> > 5) deprecated commands should be listed in the deprecated section >> of the command listing in the documentation, but not advertised in >> the documentation > > While going through the man pages, I had to rewrite several of these, > since it was describing what the documentation does, and sometimes, it > was not clear to me, what the commands were exactly about, and how it > can/should be used. Therefore, I added several examples that should > help users. The mostly rewritten man pages include: > > https://naviserver.sourceforge.io/5.0/naviserver/files/ns_adp_register.html > https://naviserver.sourceforge.io/5.0/naviserver/files/ns_set.html > https://naviserver.sourceforge.io/5.0/naviserver/files/ns_upload_stats.html > https://naviserver.sourceforge.io/5.0/naviserver/files/ns_urlspace.html > > > These are links to the new NaviServer 5 man pages. Please check. > In case, you are aware of more unclear documentation, or you would > like to see usage examples in the manual please, please contact me. I > will see what i can do. > > As discussed before, I have marked the former TDB calls mentioned > before as deprecated: > > ns_browsermatch > ns_choosecharset > ns_cookiecharset > ns_formfieldcharset > ns_formvalueput > ns_paren > ns_tagelement > ns_tagelementset > > Based on the no overwhelming feedback concerning > > ns_requestauthorize > ns_checkurl > > > My plan is to mark the latter one as deprecated and update the > documentation of the first one. > > The commands which are deprecated are not advertised as commands in > man pages anymore. However, I realized still some long-time burden: > Some parts of the documentation are still referring to deprecated > commands. > > ------------> 48 occurrences of deprecated commands in documentation > > > so, cleanup item 6 is > > 6) documentation should not be based on deprecated commands > > > After having modified a few hundred man pages, these figures don’t > shock me anymore, … but it will need again some more time. > > One more API call requiring decisions is > > ns_adp_debug > > > The call provides an interface to the TclPro debugger. I don’t have > it, so i can’t test it. Has anyone experiences with this? > > After digging around the state is: > - After Scriptics went down the TclPro suite of tools became the > ActiveState TclDevKit suite of tools > - After ActiveState stopped managing the TDK, all the sources became > open https://github.com/activestate/tdk > - There are a few forks including > https://github.com/puremourning/TclProDebug and > https://github.com/apnadkarni/TclProDebug > > The newer forks show some activity, the fork of Ashok has Tcl9 support > (but Ashok is not using it). > > My current state of mind is that we keep maintaining the interface, we > improve on the documentation and i’ll check, if the interfaces are > still the same. > > All the best > -g > > PS: I got several other mails concerning NaviServer. These are not > ignored, i will come back to you on these. > >> >> At least 1 and 2 are finished by today. This week, i have added over >> 700 tests to the regression test, which was hard work and took all my >> resources. We have now 2608 tests in the NaviServer 5 regression test >> vs. 1893 in the newest 4.99 branch: >> >> % egrep -r --include=*.test '^test ' /usr/local/src/naviserver/ >> |wc -l >> 2608 >> >> % egrep -r --include=*.test '^test ' >> /usr/local/src/naviserver-4.99/ |wc -l >> 1893 >> >> >> The current state is not perfect, but a progress. >> >> Tested commands not documented >> ------------> 706 tested commands, 72 deprecated, 648 >> documented, 0 NOT documented >> >> Documented commands not tested >> ------------> 648 documented commands, 648 tested, 0 NOT tested >> >> Deprecated commands which are documented >> ------------> 0 deprecated commands are documented >> >> >> The next goal is to check the alignment of the argument lists of the >> implementation with the documentation. >> >> On my wishlist is also a non-deprecated mode switchable via >> configuration file, where NaviServer offers only non-deprecated commands. >> >> In the meanwhile, something to think about for you: We have still a >> bunch of commands, which have a questionable future. These commands >> are in a "TBD" state for 19 years. >> >> I think, we should deprecate these commands (see below for the list) >> in the NaviServer 5 release. >> Please speak up, if your applications need these: >> >> ns_browsermatch >> ns_choosecharset >> ns_cookiecharset >> ns_formfieldcharset >> ns_formvalueput >> ns_paren >> ns_tagelement >> ns_tagelementset >> >> All the best >> -g > > > > _______________________________________________ > naviserver-devel mailing list > nav...@li... > https://lists.sourceforge.net/lists/listinfo/naviserver-devel |
