Improving RFE: Operational Meeting Discussion, Apr 2014

The 'rfe' tools seem to serve us (surprisingly) well but the large variety of maps (and differences between configured scripts), means nothing can be taken for granted; it's particularly hard to learn and remember the correct use of each map. We're proposing two simple changes to the maps and to the rfe servers' configuration which would assist in learning their use.

The changes take the form of a "mandatory" README file, which would be presented to the used following execution of a standard script on any RFE map. So, for each map, we'd expect a file mapname.README in the RFE data partition (but not in the map so as to avoid namespace clashes), accessible via a standard script (proposing "H" since it's not taken at present, but happy with sane alternatives or even renaming existing "h" scripts...):

!rfe.scripts_mapname            mADD(H)
rfe.scriptacl_mapname_H         <%rfe.readacl_mapname%>
rfe.scriptcmd_mapname_H         cat _RFE_DATA_DIR/mapname.README

the contents of the README would of course have to be left to the map manager(s) but should include:

  • the purpose of the map
  • the syntax (or reference to the syntax) used in the the map files
  • a list and functional description of all scripts defined against the map

To complete the documentation "loop" and make the new system discoverable, I'd expect the -x portion of the rfe man page to mention -xH as a standard 'help' script.

This would allow a na´ve or forgetful user the ability to discover all maps (via rfemaps or rfe tab completion) and learn their usage given only the -xH script.

Implementation

The dice/options/rfe-help-script.h file can automate this process for you:

#include <dice/options/rfe-help-script.h>
ADD_RFE_HELP_LITERAL(<mapname>)
!file.tmpl_rfehelp_<mapname>  mSET(<Help text here...>)

-- GrahamDutton - 29 Apr 2014
-- TobyBlake - 29 Apr 2014

Topic revision: r6 - 28 May 2015 - 08:08:31 - GrahamDutton
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies