Following the ROMS Conference in La Jolla, I did some research into an idea that Rich Signell had on creating an XML version of the cppdefs.h file. This week, I got back to Rich with some ideas and he asked me to post the text of my email on the discussion forum to canvas opinion on this topic. So here is an edited version of it:
The structure of the cppdefs.h file is easily transformed into XML (except for some of the more complicated rules), but the real work lies in the processing and editing of the XML document using the appropriate rules.
I have come up with an XML structure/schema for the cppdefs.h file (includes examples of possibe rules as well) and I've created an example XML document using this schema. Here is a snippet to show what it looks like:
<cppsection name="sect2" description="Model dynamics for Momentum equations">
<cppflag name="UV_ADV" parent="none">
<description>advection terms</description>
<value>false</value>
</cppflag>
<cppgroup name="Horizontal_Mixing" rules="aone" description="horizontal mixing of momentum">
<cppflag name="UV_VIS2" parent="none">
<description>Laplacian horizontal mixing</description>
<value>false</value>
</cppflag>
<cppflag name="UV_VIS4" parent="none">
<description>biharmonic horizontal mixing</description>
<value>false</value>
</cppflag>
</cppgroup>
</cppsection>
For anyone unfamiliar with XML it probably looks a bit odd, but there is method to its madness.
I've gone to the checkdefs file for the rules that need to be enforced. Some are simple and can easily be incorporated into the XML document (e.g. the idea of certain flags having a parent or parents). Some do not sit well in an XML format at all (e.g. what I call the "stop rules" at the end of checkdefs). This is where the XML processor comes in.
In my former life as an application developer I used XSLT (XML Stylesheet Language Transformation) files to transform XML into HTML which meant that the end-user was presented with a nicely-formatted web page instead of the unfriendly XML. Allowing user-interaction with the XML content meant a further step using a client-side scripting language like Javascript.
What I'm getting at here is that to make the conversion of the cppdefs.h file to XML anyway useful at all would mean developing a processor that would allow the end-user to:
(a) view the data in an organised and readable way
(b) interact with the data (e.g. turn on/off options), including being guided by the underlying rules as to which combination of options are allowed
(c) save the choices to an XML file
(d) save the choices to a cppdefs.h file that can be used by ROMS.
I've created a simple client-side processor that converts the XML into HTML and allows the user to choose options and then write the end result to XML or cppdefs.h format. This will only work on IE 6+ and is just something I put together to satisfy myself that the concept is workable. However, if anybody wants to get sample XML, the schema, and this simple application then I would be more than happy to email them to you.
I think what would be of most use to the ROMS community would probably be a server-side application hosted on the ROMS website which would allow users to create/edit their own cppdefs XML document and output the cppdefs.h file from it. Otherwise, individual users would have to create their own processors suitable to their own computing environments. Very messy, even if that is one of the reasons for using XML in the first place!
I suppose the question now is: is there enough interest out there to make this project worthwhile? In my opinion (being a complete ROMS novice) the one thing that is definitely worthwhile is an effort to make the cppdefs options more understandable (e.g. by breaking up the cppdefs file into natural sections/groups, providing more descriptive text where needed, describing the rules (which combinations of options are allowed, what options are the defaults, etc)). Of course, this would also be a precursor to conversion to XML.
Regards,
Kieran
XML form of ROMS cppdefs.h
Kieran,
This is very cool and in my opinion, *definitely* worth continuing!
I'm including a link to the zip file you sent me that demonstrates what you did:
http://stellwagen.er.usgs.gov/rps/share/xml.zip
And here's a little screen grab, just to get people jazzed on the concept:
As you say, it's not really clear what some of the cppdefs.h rules are, and this makes it very difficult for new users. Making it clear what the rules are in the form of an XML schema and if necessary, a software tool that works with the XML would be a huge contribution to usability of the ROMS system.
It would be nice if all the cppdefs.h rules could be encoded in the XML schema. But if not possible, we could enforce them in the software that reads and processes the XML, as you say.
I like the approach you suggest with a centralized "ROMS checker" web service. You could download a template xml, then submit your xml to the checker and have it spit back an updated xml and/or a cppdefs.h file. Then the rules could be updated as the code changes at a centralized location.
Of course, it should also be possible to download the "ROMS checker" application so that it could be used offline locally.
-Rich
This is very cool and in my opinion, *definitely* worth continuing!
I'm including a link to the zip file you sent me that demonstrates what you did:
http://stellwagen.er.usgs.gov/rps/share/xml.zip
And here's a little screen grab, just to get people jazzed on the concept:
As you say, it's not really clear what some of the cppdefs.h rules are, and this makes it very difficult for new users. Making it clear what the rules are in the form of an XML schema and if necessary, a software tool that works with the XML would be a huge contribution to usability of the ROMS system.
It would be nice if all the cppdefs.h rules could be encoded in the XML schema. But if not possible, we could enforce them in the software that reads and processes the XML, as you say.
I like the approach you suggest with a centralized "ROMS checker" web service. You could download a template xml, then submit your xml to the checker and have it spit back an updated xml and/or a cppdefs.h file. Then the rules could be updated as the code changes at a centralized location.
Of course, it should also be possible to download the "ROMS checker" application so that it could be used offline locally.
-Rich
-
skbhate
Without doubt this is a great approach to make ROMS more interoperable...and our effort should be towards creating a well-defined XML schema (.xsd file) which can incorporate all the cppdefs.h rules (optimistic!!!) ...once we have the schema..the user input can easily be checked before writing XML or .h file...
Rich: do you have any list of the rules for .h files defined somewhere ..or are they embedded in .h file....
Rich: do you have any list of the rules for .h files defined somewhere ..or are they embedded in .h file....