Re: Generating an HTML survey form from simple markup

[dimar]

I need to create a text describing an online survey that can be easily edited by non-techies.

I know you have probably already considered these issues jZed, but just for the sake of posterity:

Use YAML (and/or another pre-existing well-known syntax)

Thanks to YAML, there are now no more mini-syntaxes left to be invented. That's right, people, move along, there's nothing left do be done here, please clear the area.

Avoid The Perils of Positional Attributes

I offer no empirical data to back this up, but 'non-techies' and the keystroke-saving 'positional attributes' do not mix well. Why? Because generally: 1) non-techies are not going to read your mini syntax "cheatsheet" (although to your credit at least you provided one); 2) Those who do read your cheatsheet will not remember the parameters long enough to reliably put them in the right order; 3) The time they save in typing will be lost in the time it takes for them to: (a) repeatedly go back to you and ask where the cheatsheet is saved, or (b) pawn the work off on someone else down the line who is even *less* familiar with the project; AND 4) When the non-techies ask for "just one more feature" (and they will) you will have to (a) rewrite your cheatsheet, and (b) remember not to mess up the positional ordering (*headaches*)

I realize a lot of this is personal stylistic preference (which is why there are so many 'mini syntaxes' out there), but really ... learning the new 'mini syntax of the day' just gets old fast, non-techie or not.

By the way, personal experience has shown you may want to distinguish "$name" from "$caption" (i.e., the name of the field versus the on-screen "FriendlyName" that the users see.)

### YAML+XML Variant1 (no positional attributes, self 
### documenting and "extensible")
###
form_submit: action="/somepath/foobar-survey.cgi"
form_body: | 
    <input type="text" name="xxx" width="22" />
    <input type="radio" name="xxx" value1="foo" />
    <input type="textarea" name="xxx" width="22" height="11" />

### YAML+XML Variant2 if you absolutely insist on
### positional attributes and less typing
###
form_submit: action="/somepath/foobar-survey.cgi"
form_body: | 
    <!-- form for foobar-survey 2005-02-02 -->
    <text     props="name ;; 22" />
    <radio    props="name ;; foo ;; fee ;; faa" />
    <textarea props="name ;; Say Something ;; 60 ;; 4 " />

Mixing YAML and XML is surely unappealing, but it gets the job done, no new mini syntaxes were invented, and if you dont like it you can replace it with something else. Plus, using this style we get comments for free.

Update YAML+XML is mostly a kludge offered as a crutch for the "non-techies" who are (likely) already familiar with HTML, to which the XML looks similar. YAML can do all this by itself. Some points in this node were de-emphasized elsewhere in the thread.

[jZed]

Excellent points, thanks. I guess I mis-stated my goal. It is a) for me to be able to quickly write up a survey using pod markup for the non-form parts and the quickest possible and most legible but non-interfering markup for the form parts and b) for non-techies to be able to read the text file without even needing to see the cheatsheet.

The idea is much more like pod than like YAML - non-techies should be able to just read it, ignoring the =head1, etc.

Maybe the "another markup" thing is a reason for me to just use the module myself rather than CPAN it.