XSLTForms/Contributing

This page provides information for people interested in helping complete and maintain this wikibook. It describes the book's house style, sketches the current road map for improvements to the book, and provides a list of tasks that appear to need doing.

Like XSLTForms itself, this wikibook has a relatively small user community but a long life. The small community means that it may take a while for flaws and gaps in the book to be attended to; its longevity, however, suggests that the book is serving a useful function for some people. This page is an attempt to make it easier for work on the book to be coordinated and effective.

House style

Don't overcrowd pages. Make distinct topics into distinct pages (bearing in mind that pages and sections grow more often than they shrink: collaborators in a wiki are more willing to add new material than to delete material contributed by others).

Provide concrete examples. Use the syntaxhighlight element to tag them. And provide explanations and commentary to make clear what point the example is exhibiting.

Use the namespace prefixes listed in the section on Naming Conventions; if you need any namespace more than three times, it may be worth adding an entry there. Explicit namespace declarations are always OK, as long as the example remains legible.

If you leave a gap in a discussion (because you don't have time to work things out in full, or because you know a topic needs to be covered but you don't know enough to do it yourself), a comment in square brackets saying "[Fuller discussion of XYZ needed here.]" is a reasonable way to signal to readers that the coverage is incomplete and to other contributors that a gap needs filling at that point.

For consistency, it is a good idea if articles on functions and elements have roughly similar structures, with subheads for

1. Description
2. Syntax / Signature
3. Examples and uses
4. Known problems and issues
5. Further information (places to go for more details)

(A template would probably be helpful.)

When you make new pages, remember to ensure that {{BookCat}} appears at the bottom of the page.

[More details needed here.]

Road map

In the immediate future, the main task for those working on this book is to fill in the obvious gaps.

• Pages which are mentioned on (linked from) the table of contents but which do not currently exist should be created, with appropriate content.
• Topics mentioned in the table of contents that are not currently linked to a page should be described on pages of their own.
• Gaps in the prose identified by bracketed comments should be filled (and the comments removed).
• New pages should be created for topics which ought to be covered but aren't. At a first approximation: any problem that has puzzled a new(ish) user of XSLTForms for more than an hour or so should (ideally) be addressed somewhere in the Getting_Started section (perhaps under Some Common Problems). Some obvious gaps in current coverage include:
  • How to debug XForms; techniques for developing complex forms
  • Using multiple instances
  • Manage user-interface configuration (add a 'ui' instance)
  • Basics of datatypes
  • Interacting with the file system in XSLTForms; using the Java applet to read and save files

And any problem that has occupied an experienced user of XSLTForms for more than half a day or a day should (ideally) be addressed in the Further Topics or Status sections. Obvious candidates include:

• Subforms in XSLTForms
• Making file-upload work in XSLTForms; making multipart form submission work
• Basic create/retrieve/update/delete (CRUD) operations in XSLTForms
• Working with events in XSLTForms

In the longer-term future it may be desirable to restructure the book a bit for clarity, and to extend its coverage. See the Talk page for the book's table of contents for proposals.

Some things that need doing

If you don't have the time or skills to undertake any of the tasks below, but you see something that needs doing, you can help by adding it to this list!

• The contents of the page on XSLTForms-only extensions should be spun off into multiple pages, one for each extension; the page itself should be essentially a detailed table of contents listing the extensions and hyperlinking to their descriptions.

• The XSLT transformation xsltforms.xsl should be commented using a tool like XSLTdoc, and the documentation should be supplied in the page liked from the Information for Contributors section of the table of contents.

• The Javascript documentation should probably be regenerated (only in consultation with Alain Couthures).

• The list of XSLTForms extensions should be made more systematic and complete; this may require systematically reading the back archives of the support list.

• It would be very helpful if there could be working forms on this site. Anyone with the knowledge and tenacity to wade through the technical and policy information about wikibooks would do a great service by finding out whether it's possible and how to do it, if it is possible, and recording the answers here.