Motion Plugin Config File Discussion XML

Refactored from MotionPluginConfigFileDiscussion

KennethLavrsen has already decided that XML will NOT be used so there is little point in continuing arguing pros and cons. XML is nice but not as a human user interface. But it was a good discussion and it was a needed discussion.

Why not XML?

XML format has been suggested also. This format is easy to parse in the code because there are many XML libraries available. But here KennethLavrsen says a clear no. Such a format is not at all made for people to use. You will always need a tool or GUI to set the options in practical. Here is a small example of nested xml tags for a thread. Imagine the entire motion.conf like this

<camera 2>
<input_plugin>v4l</input_plugin>
<movie_plugin>ffmpeg</movie_plugin>
<v4l>
<videodevice>/dev/video0</videodevice>
<input>1</input>
</v4l>
<text_left>CAMERA 2</text_left> 
<target_dir>/usr/local/apache2/htdocs/cam2</target_dir>
<webcam_port>8082</webcam_port>
<on_picture_save>/usr/local/motion-extras/camparse2.pl</on_picture_save>
<on_movie_end>/usr/local/motion-extras/mpegparse2.pl</on_movie_end>
<ffmpeg>
<timelapse>60</timelapse>
</ffmpeg>
</camera 2>

You do not see any sain Linux programs use such a format unless it is a file related to GUI programs where humans are not supposed to edit the file like a setting file for Gnome etc.

For Motion it should still be possible to run the daemon on a headless box with no KDE or Gnome and log in with telnet or ssh and edit the config file with vi or nano or pico or whatever and then the config file must be readable, intuitive and easy to understand and use including help texts.

I have attached an example XML format motion.conf. I used the most simple XML format which means that help texts are gone. I do not find this acceptable so the real format will have to also put the help text inside tags.

<v4l>
<videodevice>
<help>
Videodevice to be used for capturing  (default /dev/video0) for FreeBSD default is /dev/bktr0
</help>
<value>/dev/video8</value>
</videodevice>

Imagine this syntax for all options and nested inside plugin tags and camera tags. I just cannot see any advantage in this format. I will drown in support requests and problems. Parsing a normal config file is not difficult. We already do it.

• Example of XML syntax with no help text: https://lavrsen.dk/foswiki/pub/Motion/MotionPluginConfigFileDiscussionXML/motion_config.xml
• Example of XML syntax with help text: https://lavrsen.dk/foswiki/pub/Motion/MotionPluginConfigFileDiscussionXML/motion_config_w_help.xml

Both example hit a KennethsNerdoMeter score of 8 or 9. We cannot possibly expect a user to understand, overview and edit such a complicated file. Even when you look at the files in an XML viewer the structure gets so complexe that you loose any overview. The attached examples are made so show with a real live example how scary the files get. XML is great for data that only a machine will read and write. But it was never intended to be manually edited.

Let me try and list the things I see are clear disadvantages with pure XML config files.

• The real information drown in the many XML tags when a human looks at the file.
• To be valid XML comments and help text must be inside XML tags as well. You can add more help text but they again end up inside tags and the whole thing becomes a mess to look at.
• The user needs to be careful with the syntax. One missing < or / and the reading fails.
• You loose the ability to easily comment out an option or have the same option 3 times with a comment sign in front of two of them.
• When people post their config options on the mailing list - they now need to post the entire scope around it - several lines instead of just one line.
• People editing the config file with vi or nano via a telnet session will have a hard time navigating and finding the right place to edit.
• You have a hard time finding an option because the option name drowns in all those tags. You will have to use the search function in your editor.
• It will become difficult to use whitespace to seperate and group options that belong together.

Advantages or are they????

• XML is a smart and universal way to store data instead of propritary binary database formats etc. (but a config file is not a database or an office document and plain text config files are pretty smart and universal too for their purpose)
• XML syntax is a standard (and??? XML tags are standard but how you use them in a config file is not at all part of the standard. The two examples I have made are quite different from each other - with help and without - but both fully valid XML files).
• XML files are easy to parse in software. (Yes. And plain text config files are even easier and we do that already today to this is extra work).

What is it we win with pure XML? Actually nothing. Plain config files are already kind of nerdy. But if we change to XML we loose half our "customers". Experienced programmers are probably in favour of these nerdy solutions but most Motion users are not programmers. Also note that even newer non-GUI type Linux programs and tools still choose to use plain text good old "option value" plain text config files.

Further discussion of XML

I really hesitate to comment further, because I am not very stongly in favour of XML - only that if we are going to examine it, and consider it's pros and cons, then at least we should be considering a file which demonstrates a layout which a person (at least a nerdy type like me) can easily read and understand. I have re-formatted Kenneth's original example file and attached it as motion_config_v2.xml.

To me, the major advantages are the ability to easily validate the "correctness" of the file, and the availability of a large number of utility programs and runtime libraries to manipulate it. On the other hand, the argument concerning how difficult it would be for a newbie to try to manually edit it to make a relatively simple change is certainly a very strong one, and even if we were to decide on holding the configuration in an xml-form, it would be vitally important to provide some method for the user to edit the file (for example, like Swat can be used for Samba) in a user-friendly manner. -- BillBrack - 04 Oct 2005

Thanks Bill. For sure much more readable format and much better than mine. But if you translate the version including the help texts and also add the section help texts (incl the most important conversion specifiers) then it gets more complicated.

I remember the time we had where the help texts in motion.conf were reduced from 2-3 lines per option to one single line (when the ability to save config files from Motion was added). The number of support questions increased dramatically. I had to change it so that Motion saved multiple lines of help text. The help texts are an important part of the user interface. pre_capture feature was continuously used with too large values until I added several lines of help text guiding people to use reasonable values

The two things that makes XML less friendly to the user is the struct syntax requirement (the start and end tags, the right tags words, the quotation marks in this case) and the readability. I myself hate it. When I created the two examples I constantly had to search for the text when moving comments from one file to the other. I am 100% convinced against XML now. Making a better and ADDITIONAL way to edit the config files has always been a high priority and the http interface is an attempt of doing that - which still has a lot of potential for improvements. And there are other alternatives that can be implemented no matter which format we use. As I keep on saying. We programmers can make any format work. So my main concern is the user. And even though being experienced Motion user I personally HATE the xml config file examples. So I would like to try and stop the XML debate and have the ball rolling on the other ideas AND new ideas -- KennethLavrsen - 04 Oct 2005

-- KennethLavrsen - 08 Oct 2005