The following two commands, is-valid-template and register-template, are not used in regular operation. The first two are used when creating new templates for use with Yaktrack, and the third is a command to access Yaktrack's configuration management commands (used internally by Yaktrack)
The is-valid-template command is used to check and see if a given text file represents a valid yaktrack template. Yaktrack uses standard XML Document Type Definition format to define issue templates. However, the full XML standard is extremely complex, and so Yaktrack can only accept a small subset of XML at this point (this may be expanded as Yaktrack matures). In particular:
No processing instructions are allowed
No entity declarations (general, external, parameter...) are allowed
No notations are allowed
Elements may not contain subelement groups
Elements may not contain repeating or optional subelements
The first element in the template must contain a CDATA attribute named "yaktrackid" which is #IMPLIED
All element attributes must be #REQUIRED, #IMPLIED, or have a default value
Only #PCDATA or enumerated attributes are allowed
While this seems restrictive, it still allows for a very flexible notation and use. With further evolution of Yaktrack, some of these restrictions will probably be lifted.
In the meantime, however, the is-valid-template command can verify an on-disk template for validity according to the above rules. In the following example, the user is attempting to create a new issue type, but violates some of the rules:
[vputz@yak_prime temp]$ cat bad_template <!ELEMENT foo (bar, baz, bon) > <!ATTLIST foo badatt CDATA "bob" > <!ELEMENT bar ( baz, bon+ ) > <!ELEMENT baz ( #PCDATA ) > <!ELEMENT bon ( #PCDATA ) > [vputz@yak_prime temp]$ ../yaktrack.py is-valid-template bad_template DTD bad_template is invalid for use with yaktrack: invalid subelement bar/bon; contains modifier Root element does not contain an #IMPLIED text attribute named 'yaktrackid' |
Once you have a valid template, you can use the register-template command to actually store the template in the repository. The requested template file is loaded and checked for validity as per the is-valid-template command. If valid, the template is stored in the repository under the name of the first element encountered -- which is not necessarily the filename! For example, suppose our user from before fixed the problems in bad_template and registered it:
[vputz@yak_prime temp]$ cat bad_template
<!ELEMENT foo (bar, baz, bon) >
<!ATTLIST foo badatt CDATA "bob"
yaktrackid CDATA #IMPLIED >
<!ELEMENT bar ( baz, bon ) >
<!ELEMENT baz ( #PCDATA ) >
<!ELEMENT bon ( #PCDATA ) >
[vputz@yak_prime temp]$ ../yaktrack.py is-valid-template bad_template
DTD bad_template is a valid yaktrack template.
[vputz@yak_prime temp]$ ../yaktrack.py register-template bad_template
Template foo was stored successfully.
[vputz@yak_prime temp]$ |
Note that the name used by Yaktrack to store the template ("foo") is not the name of the template file (bad_template, but is rather the name of the first element. Now that the template is stored, the user can immediately begin using it to submit new items:
[vputz@yak_prime temp]$ ../yaktrack.py submit foo foo /home/vputz/projects/class/yaktrack/src/temp/yaktrack-repository Attribute: (foo:badatt) Old/Default contents: bob [return keeps contents] >> ... |
You cannot register a template whose name is already taken, which means that you can't resubmit templates, either (allowing this might break the repository, since you could change the template for existing issues, which might make them invalid). This may be changed in a future release, but for now, make sure you have the issue template correct before submitting it!