.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 (from the 'dev' dir), which also serves as the example file found in dev/scripts/template.help.xml:

emacs 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 (for example in dev/mri_my_program), do this:

cp mris_inflate/mris_inflate.help.xml mri_my_program/mri_my_program.help.xml
add this to your .c file, whereever --help is called:

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

add these lines to the Makefile.am file:

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) $(BUILT_SOURCES)

edit mri_my_program.help.xml as appropriate
cvs add mri_my_program.help.xml
cvs commit

Some things to note: emacs understands .xml files, and one step to take before commiting a file is to run SGML->Validate, to check your .help.xml file. The 'make check' for the Makefile.am will also run xmllint (via scripts/help_xml_validate) on the file to catch mistakes.

The DTD can be editted to add new stuff if desired.