JIMRI/xml/XSLT/README

README for xml/XSLT in the JMRI distribution.

See COPYING for license information.

This contains XSLT transformations of the XML information maintained
by the JMRI project.  build.xml is the ant build control file for
performing these transformations. In general, these transformations put 
their results in "pages" subdirectory that is not present in CVS.

Common & summary Ant targets:

 	xslt		run the whole sequence of processing

	init    	create needed directories
	clean   	remove compilation results to force rebuild
	copyDTD		ensure local DTD file copies present where needed for processing
	copyXML		ensure local XML file copies present where needed for processing
 
Create the by-decoder web pages and index:

	index 		create a decoder index page
 				uses DecoderModelIndex.xsl
 			
	models		tranform definitions into web pages
 				uses DecoderModelList.xsl
 
Create other views as web pages:			

	selection	create HTML decoder selection guide listing various properties
 				uses SelectionGuide.xsl
 	
 	cvsummary	create HTML page listing CVs available on all decoders
  				uses CVsummary.xsl, interestingCVs.xml
 
Create views as CommaSeparateVariable files:

	csv			create CSV file listing CVs available on all decoders
 				uses CSVsummary.xsl, interestingCVs.xml
 			
 				create CSV file listing decoder sizes
 				uses SizeAsCSV.xsl
 				
 				create CSV file listing decoder power limits
 				uses PowerAsCSV.xsl


Information on specific XSLT tranforms:

decoder.xsl     used as a stylesheet by decoder XML files for web display;
                creates an update form
                
DecoderID.xsl   used by Ant "id" target and used as an XML stylesheet to 
                display the decoderIndex.xml file.
                
panelfile[VERSION].xsl   stylesheet for JMRI panel files

locomotive.xsl  stylesheet for JMRI roster entry files

roster.xsl      stylesheet for JMRI roster index

rpsfile.xsl     stylesheet for JMRI RPS files

throttle-config.xsl    stylesheet for individual throttle config files
                [Uses throttle-include.xsl]

throttle-layout-config.xsl    stylesheet for default (JMRI_ThrottlePreference.xml) and user-named layout config files
                [Uses throttle-include.xsl]

LogixToCode.xml Tool for creating Java code from the Logix and Routes
                in a panel file.  The code will (with a little adjustment)
                recreate the contents.



Processing decoder files:

normalizeDecoder is a shell script that runs the standard series of processings
on an set of input files, followed by xmllint to put it in standard layout.

Those operations can be tested with the ./testDecoderTransforms script.

Operations:
    move variable@label to variable@item if no @item exists
    make variable{label] elements from attributes
    remove variable@label if redundant
    
    move label/label to label/text
    move label@label to label/text
    remove label@label
    

Still needed:

(Is normalize not creating a default choice element?  Will I18N 
notice if there's a default choice _element_?)
>       <enumChoice choice="No">
>         <choice xml:lang="de">No</choice>
>       </enumChoice>


What does this attribute on <pane> really do?
    <xs:attribute name="nameFmt" type="labelItemType" default="label">
      <xs:annotation><xs:documentation>
      Specifies whether the text displayed in the interface should
      come from the "item" or "label" of the underlying variable.
      </xs:documentation></xs:annotation>
    </xs:attribute>
    Only used in a couple of programmers
        JMRI/projects/HEAD/xml/XSLT/ % grep -r nameFmt ../programmers/
        ../programmers//Basic.xml:    <pane name="Basic" nameFmt="item">
        ../programmers//Registers.xml:    <pane name="Basic" nameFmt="item">
        ../programmers//Tutorial.xml:    <pane name="Decoder Address" nameFmt="item">
        ../programmers//Tutorial.xml:    <pane name="Enums" nameFmt="item">
        ../programmers//Tutorial.xml:    <pane name="Values" nameFmt="item">
        JMRI/projects/HEAD/xml/XSLT/ % grep -r nameFmt ../decoders
        ../decoders/Arnold_81220.xml:	<pane name="Arnold" nameFmt="item">
        ../decoders/MRC_Rapido_TurboTrain.xml:  <pane name="MRC" nameFmt="label">
        ../decoders/Umelec_ATL2051.xml:  <pane name="Speed Table" nameFmt="label">
        ../decoders/Umelec_ATL2051.xml:  <pane name="Whistle" nameFmt="label">
        ../decoders/Umelec_ATL2051.xml:  <pane name="ATL Motor" nameFmt="label">
        ../decoders/Umelec_ATL2064.xml:  <pane name="ATLPlus" nameFmt="label">
        ../decoders/Umelec_ATL2064.xml:  <pane name="Signal Mode" nameFmt="label">
        ../decoders/Umelec_ATL2064.xml:  <pane name="ATL Other" nameFmt="label">

0) process away tooltip and comment attribute in variables (and tooltip in panes!), making
    proper sub-elements

1) Add <comment xml:lang=""> elements in decoderAddI18N,
    but only if there are others already (might be easiest to just replicate the default one)

2) Order subelements by language for simplicity, see:
    http://stackoverflow.com/questions/572854/how-to-sort-a-subelement-of-xml-with-xslt
    


Eventual goal is to update schema to enforce regular structure:
    variable element:
        remove label, comment, tooltip attributes in favor of elements
        label contains text, not label
        choice attribute on enumChoice element
        
    pane element:
        label contains text, not label
        remove tooltip attribute from display element in favor of elements
       
PaneType has too free a schema for the top element, as it allows multiple
copyright, etc, in the process of allowing multiple name element.  In particular,
it doesn't enforce a single row/column at top level, which the program requires.
       
Eventually want a constraint that qualifier variablerefs are present, but how to get that?
Pane files don't know about the primary decoder file.  (So need it programmatic? Even then,
matching problematic)

      <xs:element name="variables" type="VariablesType" minOccurs="1" maxOccurs="1">
        <xs:unique name="UniqueVariableItemAttribute2">
          <xs:annotation><xs:documentation>Insist that the variable item attribute is unique</xs:documentation></xs:annotation>
          <xs:selector xpath=".//variable"/> 
          <xs:field xpath="@item"/>           
          <xs:field xpath="@include"/>           
          <xs:field xpath="@exclude"/>           
        </xs:unique>

        <xs:keyref name="QualifierKeyRef2" refer="UniqueVariableItemAttribute2">
          <xs:selector xpath=".//variable/qualifier"/>
          <xs:field xpath="variableref" />
        </xs:keyref>

      </xs:element>

The above doesn't work because QualifierKeyRef2 needs to have three fields.