doc: Introduce diff_with_c-version.pod document

doc/Makefile

@@ -12,7 +12,8 @@ MAN4_DIR := $(MAN_DIR)/man4
 SOURCE_DIR := source
 
 all: $(HTML_DIR)/module.html $(HTML_DIR)/modulefile.html \
-	$(MAN1_DIR)/module.1 $(MAN4_DIR)/modulefile.4
+	$(MAN1_DIR)/module.1 $(MAN4_DIR)/modulefile.4 \
+	$(HTML_DIR)/diff_with_c-version.html
 
 $(HTML_DIR)/%.html: $(SOURCE_DIR)/%.pod $(VERSION_FILE)
 	mkdir -p $(HTML_DIR)

doc/source/diff_with_c-version.pod

@@ -0,0 +1,115 @@
+=head1 Slight differences with C-version
+
+This document lists the differences of the functionalities that can be found on the C-version of the Modules package compared to the Tcl-version. The goal of this document is to reference the features of the C-version that are missing or behave differently on the Tcl-version. These information help to clearly know what functionalities was there on C-version that will change in case of migration to the Tcl-version.
+
+This document does not cover the features of the Tcl-version that are not available on the C-version (like collection management, Fish or Tcl shell support, etc). Please refer to the B<module>(1) and the B<modulefile>(4) man-pages of the Tcl-version to discover all the functionalities provided by the Tcl-version of the Modules package.
+
+=head2 Package Initialization
+
+Tcl-version does not support I<cmake> and I<ruby> as code output.
+
+B<MODULESBEGINENV> environment snapshot functionality is not supported on Tcl-version.
+
+=head2 Command line switches
+
+Command line switches relative to a sub-command must be specified on the command line after the sub-command. For instance C<module --terse list> will raise an error on Tcl-version, C<module list --terse> should be used instead.
+
+=over
+
+=item B<--force>, B<-f>
+
+=item B<--human>, B<-h>
+
+=item B<--verbose>, B<-v>
+
+=item B<--silent>, B<-s>
+
+=item B<--create>, B<-c>
+
+=item B<--icase>, B<-i>
+
+=item B<--userlvl> lvl, B<-u> lvl
+
+These command line switches are not supported on Tcl-version.
+
+=back
+
+=head2 Module Sub-Commands
+
+On C-version, paths composing the B<MODULEPATH> environment variable may contain reference to environment variable. These variable references are resolved dynamically when B<MODULEPATH> is looked at during module sub-command action like B<avail>.
+
+=over
+
+=item B<clear>
+
+=item B<update>
+
+These module sub-commands are not supported on Tcl-version.
+
+=item B<refresh>
+
+On C-version, only the shell aliases defined by the currently loaded modulefiles are set again on a B<refresh> command. Whereas on Tcl-version this command is an alias on the B<reload> command that B<unload> then B<load> all the currently loaded modulefiles.
+
+=item B<help>
+
+C-version redirects output made on stdout in B<ModulesHelp> Tcl procedure to stderr.
+
+During an B<help> sub-command, only the B<ModulesHelp> Tcl procedure of a modulefile is interpreted on C-version. Tcl-version interprets all the content of the modulefile, then call the B<ModulesHelp> procedure if it exists.
+
+=item B<load>
+
+On Tcl-version the value of an environment variable is set even if the new value is the same as the current value of this variable in environment.
+
+=item B<switch>
+
+When switching on Tcl-version an I<old> modulefile by a I<new> one, no error is raised if I<old> modulefile is not currently loaded.
+
+When switching on Tcl-version an I<old> modulefile by a I<new> one, this I<new> modulefile does not keep the position that the I<old> modulefile had in the B<LOADEDMODULES> list as done on C-version but it is appended to the end of the list. Same goes for PATH-like environment variables: replaced PATH component is appended to the end or prepended to the beginning of the relative PATH-like variable, not appended or prepended relatively to the position hold by the swapped PATH component.
+
+=back
+
+=head2 Modules Specific Tcl Commands
+
+=over
+
+=item B<exit>
+
+On Tcl-version code passed to the B<exit> Modules specific Tcl command will not be thrown to be the B<module> return value.
+
+=item B<module-info>
+
+=over
+
+=item B<module-info flags>
+
+=item B<module-info trace>
+
+=item B<module-info tracepat>
+
+=item B<module-info user>
+
+These B<module-info> options are related to C-version specific features so they are available on Tcl-version but with a dummy implementation that always returns false or an empty value.
+
+=item B<module-info mode>
+
+During an B<unload> sub-command, I<unload> is returned instead of I<remove>. However if B<mode> is tested against I<remove> value, true will be returned.
+
+During a B<switch> sub-command, I<unload> then I<load> is returned instead of I<switch1> then I<switch2> then I<switch3>. However if B<mode> is tested against I<switch> value, true will be returned.
+
+=back
+
+=item B<module-log>
+
+=item B<module-trace>
+
+=item B<module-user>
+
+=item B<module-verbosity>
+
+These Modules specific Tcl commands are related to C-version specific features so they are available on Tcl-version but with a dummy implementation that always displays a warning message saying the command is not implemented.
+
+=item B<module-whatis>
+
+When multiple words are passed as argument to B<module-whatis> but they are not enclosed in double-quotes or curly braces they will be displayed as a single line on Tcl-version whereas C-version displays them as one line per word.
+
+=back