About the Syntax of XML Config files

[Hanbing59]

Hi,

I just started to read the XML config files of GROOPS. As I am new to XML, I have briefly scanned the XML standard syntax from W3Schools a little bit. My wondering is:

do GROOPS XML files comply fully with the standard (very simple though) syntax? By which I mean, I know the XML files are mainly read && wrote by the GROOPS GUI, and apparently only a set of recognizable elements (groops, global, program, LoopPrograms, the specific programs from GROOPS, attributes of each programs, ...) are meaningful or correspond to some display ares on the GUI window, how about those non-recognizable ones? Like some user-defined elements or attributes added for human reading? Would those elements added by users interrupt the running of GROOP or GROOPS would just ignore them? For example, I notice that, for the element program, there is usually a comment attribute, which I guess would appear along the program to provide a short explanation. Users may sometimes would like to add those comment attributes to many other elements (I think not for all elements there is a specific area on the GUI to show comments, right?), would this corrupt the config files?

I think it would be more beginner-friendly if more description or explanation about the XML config files could be added to the documentation, especially on

• the corresponding relationship between a standard XML file and a XML-style GROOPS config file
• some notes about recognizable elements and any consequences from un-recongnizable elements or attributes.

Please correct me if I misunderstood something about the philosophy behind the design. Once I am confident that I know it very well, I am happy to add some notes into the documentation if I may.

Thanks in advance.

[tmayerguerr]

Hi Hanbing,

The idea is to make GROOPS as easy to expand as possible without requiring knowledge of HTML, XML or GUI programming. If you want to add a new programm to GROOPS, all you need to do is add a single .cpp file (see #346).

From the Latex docstring at the begin of the file the documentation is build (see #388).

The code itself always starts with a series of readConfig() commands that read (and define) the settings of the program. The command

groops --xsd groops.xsd

generates an XML schema file (which is itself an XML file) from all readConfig() lines, which describes all XML elements of the configuration files with their names and types. This then reads the GUI in order to display the elements accordingly.

In principle, this schema file is a machine-readable definition of what a configuration file must look like. In the early days of GROOPS, the definition followed the standard (https://www.w3schools.com/xml/schema_intro.asp) exactly and could be used to validate configuration files. However, we have since had to expand the definition (e.g. defaults for complex elements) and the XML configurations no longer follow the schema exactly (variables can now appear anywhere, not just in the global section).

To clarify and to answer your first question. GROOPS XML files are fully compliant with the standard (which defines only the structure but not the name of the elements), and described by the schema file (with minor exceptions).

The comment attribute can be edited in the GUI for each element in the fourth column (Type/Value/Description/Comment). Simply double-click on it.

GROOPS ignores unknown elements (are warning is released) .

Since neither users nor programmers come into direct contact with the XML files, I do not consider it useful to include this in the documentation.

I hope this has helped a little in understanding.
Best regards
Torsten

[Hanbing59]

Hi Torsten,

thank you very much for your detailed reply.

As I am still at the very early stage to get along with GROOPS, it might take some time for me to fully digest your information. So, I'll come back to you a little bit latter if necessary.

Thanks again for your time and efforts on making GROOPS as open as possible.

Regards,
Hanbing