Documentation Conventions ========================== The following are conventions used in this manual, and elsewhere when documenting programming, scripting, and other technical topics. Metasyntactic Variables ------------------------ There is often the need for a placeholder value to indicate parts of a script, file path, or similar string that should be replaced with a specific value in practice. We place these in all caps (which is unusual in most of our code contexts) and use the venerable words from the early days of programming at MIT and Stanford: * FOO * BAR * BAZ * QUX * QUUX * CORGE * GRAULT * GARPLY * WALDO * FRED * PLUGH * XYZZY * THUD Here is an example used to describe a generic scripting pattern, a for-each loop where FOO is the current iteration value and BAR is the collection iterated over:: for (FOO in BAR) { log.info(FOO); } And here is an example of usage when describing a file path for a module file, with FOO as the config level (e.g. "seat") and BAR as be the module name (e.g. "Tracing"):: modules/FOO/BAR/info/depends.txt Sometimes we use all caps (to designate that it's a metasyntactic variable) but choose a more meaningful name, e.g.:: modules/CONFIGLEVEL/MODULENAME/info/depends.txt See http://www.catb.org/jargon/html/M/metasyntactic-variable.html and http://en.wikipedia.org/wiki/Metasyntactic_variable for a more detailed treatment of metasyntacity.