[Pipet Devel] XML descriptions for loci

[Jean-Marc Valin]

> The biggest thing to note is that I changed the name "node" to now be
> "locus". The reason I did this is that node just conflicts too much with
> DOM, and it makes things confusing, in my opinion. I know that "locus"
> might not be that descriptive to start with, but at least it is unambiguous
> when you see it, unlike node (or pnode or piper_node or whatever). Other
> suggestions for names are always welcome :-).
> 
> Below is the description of a locus constant (Constant.cc from the Overflow
> code).
> 
> <!--Constant.xml
> Locus type describing a constant value.
> -->

I would remove this comment and put it in the definition so it can be used from
Piper

> 
> <!DOCTYPE piperplugin SYSTEM "piperplugin.dtd">
> 
> <piperplugin>
>   <module name = "General">
>     <locus name = "Constant">
> 
>           <parameter name = "constant_value" type = "ANY" />
>           <output name = "output_constant" type = "ANY" />
> 
>         </locus>
>   </module>
> </piperplugin>

I suggest something like:
<piperplugin>
    <locus name = "Constant" module="General">

          <parameter name = "constant_value" type = "ANY" />
          <output name = "output_constant" type = "ANY" />
          <comments> Locus type describing a constant value. </comments>
        </locus>
</piperplugin>

If each node definition is in its own XML file, the module name can just be a
property. Also, this is just a detail, but I suggest not to use a .xml extension
since most of the piper files will be XML files.

> <!--ls.xml
> The ls command represented as a piper plugin. This is the representation of
> how 'ls -l' would look.
> -->
> 
> <!DOCTYPE piperplugin SYSTEM "piperplugin.dtd">
> 
> <piperplugin>
>   <module name = "unix">
>     <module name = "utilities">
>           <locus name = "ls">
> 
>             <plugin_link xlink:href = "IO/NetExec.xml">
>                   <connect xlink:to = "command" xlink:from ="ls_name"/>
>                   <connect xlink:to = "arguments" xlink:from = "ls_options"/>
>                 </plugin_link>
> 
>                 <plugin_link name = "ls_name" xlink:href =
> "General/Constant.xml">
>                   <substitute xlink:to = "constant_value" value = "ls"/>
>                 </plugin_link>
> 
>                 <plugin_link name = "ls_options" xlink:href =
> "General/Constant.xml">
>                    <substitute xlink:to = "constant_value" value = "-l"/>
>                 </plugin_link>
> 
>                 <description>
>                 ls -l
>                 List the long contents of the current directory.
>             </description>
> 
>           </locus>
>         </module>
>   </module>
> </piperplugin>

I may be missing something, but that seems to be too compilicated and I don't
see the gain.

	Jean-Marc

-- 
Jean-Marc Valin
Universite de Sherbrooke - Genie Electrique
valj01 at gel.usherb.ca