fopa:SyntaxNotes

From NITRC Wiki

Notes on document: http://www.nitrc.org/docman/view.php/238/612/Proposed-NAMIC-XML-CLI-Syntax-v0-4.docx

1) On the motivation page, para 1 - it is not clear to me by what one means by "Any number of programs may be included in the response" - If this statement refers to plug-ins or modules that the executable being queried can invoke then it might be a better idea to have a seperate tag say <invokable> or <modules> which explicitly lists these (installed /available) plugins and modules. This would allow the calling program to differentiate between inbuilt and modular functions.

2) The flag tag in the parameters section (current draft) provides an implicit way of defining dependencies between parameters and flag parameters.I would recommend that following tags be added so we can explicitly identify a flag parameter and its dependencies. The new tags are shown below :

<Parameter>
	<id>...</id>
	<Flag value="Y" dependent="">		REQ! - The dependent tag includes the name of the flag if the parameter itself is not a flag
		<Parameter id="...."/ required="Y/N">			OPT*
		.....
	</Flag>

3) I would not recommend supporting html in descriptions for now

4) Another suggestion would for parameters which require a file input say an image, we should have a tag that lists all the supported file formats.

	Ex:
	<Paramater>
		<Id>in</Id>
		<Class>in</Class>
		<Type>resource.image</Type>
		<SupportedFormats>									                        OPT*
			<Format name="Analyze"	ext="hdr"  minversion="2.x" /> 				OPT!
			<Format name="Minc"	        ext="mnc" minversion="5.x" maxversion="10.x"/>
		</SupportedFormats>
		...
	</Parameter>

5) A tag explaning program return codes. Some of the codes are specific to the OS, but other codes can be used to indicate errors to the calling program. Ex:

	<Program>
	.
	.	
	<ReturnCode>
		<Code value="127">
			<Description>Unable to parse image file. Unknown format</Description>
			<HMReadable>UnknownFormatException</HMReadable>
		</Code>
		<Code value="150">`a
			<Description>JVM ran out of memory. Try increasing memory and call the program again</Description>
			<HMReadable>OutofMemoryException</HMReadable>
		</Code>
	</ReturnCode>
	</Program>