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 naviserver-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/naviserver-devel
