.help.xml

This page describes how the help text associated with a freesurfer executable is created in XML format and displayed. This page documents the work output of ProjectHelp by Greg Terrono, focusing only on the .help.xml file which contains the help text.

To get right to it, assuming you have a CVS checkout of the dev tree, look at this file, which also serves as the example file found in dev/scripts/template.help.xml: 

emacs dev/mris_inflate/mris_inflate.help.xml

This is an example help text file. The DTD is at the top of the file, and the entities it contains closely match what you would see in a unix man page. To see the help text: 

mris_inflate --help

The routines /dev/utils/fsPrintHelp.c are used in the source code (mris_inflate.c) to print the .help.xml file to screen (after converting to a .h file and embedding).

So to create the help text file for a new program (in dev/mri_my_program), do this: 

#include "mris_inflate.help.xml.h"
static void
print_usage(void)
{
  outputHelpXml(mris_inflate_help_xml,
                mris_inflate_help_xml_len);
}

BUILT_SOURCES=mris_inflate.help.xml.h

foodir=$(prefix)/docs/xml
foo_DATA=mris_inflate.help.xml

TESTS=$(top_builddir)/scripts/help_xml_validate

EXTRA_DIST=$(foo_DATA)