Talk:XSLTForms

Contributors documentation
Does the heading "Contributors documentation" mean "Documentation for contributors to the XSLTForms project"? or "Documentation contributed by others"?

If it's the former (i.e. if the idea is to go into code internals here), then perhaps (a) the section heading should be changed, and (b) perhaps the CSS page should move up into the part of the wikibook intended for users. (Forms authors need to know those CSS class names!)

If it's the latter, then this probably should not be a section of its own, but the pages should be placed in logical positions in the overall book.

I have not made any change, though, because I'm not sure what is intended.

Cmsmcq (talk) 20:51, 18 September 2010 (UTC)

It is to be considered as the former: "Documentation for contributors to the XSLTForms project".

I'll change the section heading accordingly.

Thanks!

-Alain --Alain Couthures (talk) 18:50, 21 September 2010 (UTC)

The XLST 1.0 link broken
Under:

Documentation for contributors:

1. XSLT 1.0 stylesheet

the link is broken.

Cppljevans (discuss • contribs) 14:01, 29 October 2013 (UTC)

-

I interpret that as a consequence of someone setting out an initial plan (info for contributors should include info about the XSLT stylesheet and about the Javascript) and making the two hyperlinks as a sort of promissory note, then creating the page for Javascript information but not (yet) creating the page for the XSLT stylesheet.

Given that the Javascript section is auto-generated, perhaps the simplest thing to do would be to use a similar auto-generation tool for XSLT documentation for the XSLT section. Perhaps XSLTdoc would be appropriate. (I have no experience with it or similar tools; I have always documented my stylesheets by hand.)

The Javascript documentation should probably also be regenerated -- judging by the edit history, it hasn't been regenerated from scratch for several years.

CMSMcQ (discuss • contribs) 18:15, 8 February 2017 (UTC)

Restructuring?
I'm beginning to think the book could make a better impression on new readers, and be more useful, if (a) the organization were a little clearer, and (b) there were fewer visible gaps.

Ideally, I think, those of us interested in XSLTForms should make the book into the kind of documentation we would like XSLTForms to have, and the kind of documentation we can direct new users to with confidence.

This book as a general introduction to XForms?
In the best of all possible worlds, I think, the book should serve both as a tutorial for people learning XForms and using XSLTForms as their implementation, and as a reference manual for experienced users. The easiest way to achieve this would be with a top-level organization something like this:


 * 1) Introduction (about the book, about XForms, about XSLTForms, ...)
 * 2) Gettting Started (a tutorial introduction to XForms, using XSLTForms)
 * 3) * Installation (subsections on Apache; other web servers; ASP.NET (?); eXist-db; any other environments that require special information)
 * 4) * A hello-world example (testing to see that the installation works)
 * 5) * The basics of XForms (M/V/C,,  ,  , controls in the document body, ...)
 * 6) * Tutorial example 1 (relatively simple XML document, basics of controls)
 * 7) * Tutorial example 2: tabbed interface (more complex document to motivate tabs)
 * 8) * Tutorial example 3: repeating elements
 * 9) * Some common problems (form doesn't display right; buttons don't work; instance doesn't load; same-origin policy in browser)
 * 10) * Some useful infrastructure for development (displaying the XML by submitting it to a show-the-instance script on the server; displaying the XML by using ; mirroring foreign resources to work around same-origin issues; setting up WebDAV with Apache to allow PUT)
 * 11) Further topics (mix of tutorial and reference style)
 * 12) * Subforms
 * 13) * Datatyping and validation
 * 14) * Error diagnosis, error message, user help, hints
 * 15) * Using multiple instances (including an instance to keep track of user-interface configuration)
 * 16) * Working with mixed-content editors (TinyMCE, CKEditor)
 * 17) * Working with variable-depth data (e.g. expression languages)
 * 18) * Basic operations (CRUD)
 * 19) * Performance issues and optimization
 * 20) * Working with events
 * 21) XForms / XSLTForms reference manual
 * 22) * XForms elements (alphabetical list, including extensions)
 * 23) * generic attribute (attributes found on more than one element (? are there any?)
 * 24) * XPath functions (alphabetical list, including extensions)
 * 25) * CSS pseudo-classes
 * 26) * XSLTForms-specific extensions and restrictions (concise summary, pointing to the relevant entries in the main lists)
 * 27) Internals of XSLTForms (for project contributors)
 * 28) * The XSLT transformation
 * 29) * The Javascript

The sections currently headed Beginning Examples, Using XSLTForms, and Solution to Common Problems would all move into the Getting Started section.

Parts of the section currently headed 'Status' would go in the reference manual; the sections on TinyMCE and performance would go into the 'Further topics' section.

A less ambitious goal
In the short run, however, adding a full tutorial introduction to XForms, and a full reference manual of XForms written with special reference to XSLTForms, may be beyond our resources. We can make a useful book, however, if we try to make the book contain a complete guide to the things you need to know in order to use XSLTForms but cannot learn by looking at the spec, or at other generic resources for XForms. A book that focuses just on XSLTForms-specific information can use an outline very similar to that given above; instead of a tutorial introduction to XForms, however, the second section would point to other resources for that and limit itself to introductory information needed by XSLTForms users. The outline would look more like this (changes only to Getting Started and Further Topics):


 * 1) Introduction ...
 * 2) Gettting Started (information for new users of XForms and XSLTForms)
 * 3) * Installation (subsections on Apache; other web servers; ASP.NET (?); eXist-db; any other environments that require special information)
 * 4) * A hello-world example (testing to see that the installation works)
 * 5) * Learning the basics of XForms (pointers to tutorials, resources, the spec, ...)
 * 6) * Some common problems (form doesn't display right; buttons don't work; instance doesn't load; same-origin policy in browser)
 * 7) * Some useful infrastructure for development (displaying the XML by submitting it to a show-the-instance script on the server; displaying the XML by using ; mirroring foreign resources to work around same-origin issues; setting up WebDAV with Apache to allow PUT)
 * 8) Further topics (mix of tutorial and reference style)
 * 9) * Subforms in XSLTForms
 * 10) * Datatyping and validation in XSLTForms
 * 11) * Error diagnosis, error message, user help, hints in XSLTForms
 * 12) * Working with mixed-content editors (TinyMCE, CKEditor)
 * 13) * Performance issues and optimization in XSLTForms
 * 14) * Working with events in XSLTForms
 * 15) Reference manual ...
 * 16) Internals ...

The reference section would not summarize what's in the spec, but would for each construct in the spec mention any known particularities of the implementation in XSLTForms. The reference material should describe (a) the most recent 'stable' version (at the moment that would be 1.0RC2 of a few years ago) and (b) the most recent SourceForge version (specific release numbers should be given, to reduce confusion).

Moving forward? How to make the book more complete?
How to generate a more complete reference section?
 * One way would be to work carefully through the test suite, recording each place where there is a gap in or a limit on the implementation. This would be very enlightening for whoever did it. The only problem is that that would take a lot of time.
 * Another way to come closer to completeness would be for people who find themselves having to figure out how to use some construct to pause, after they have figured it out, and write it up. In that way, the features most frequently used get documented first
 * A third approach would be to scan through the archives of the support mailing list to find (a) what people most often report problems with, and (b) extensions which should be documented here.

An open question: How can we provide a table of contents or structure for the book which (a) provides a kind of road map for future development, (b) makes clear where new topics should fit in (assuming that there is a natural place for them), and (c) doesn't look like something half-finished, with more gaps than completed sections? (The negative way to interpret this question is: how do we make the book look more finished than it is?  A more positive slant is:  how do we present the material we have to best advantage?)

A possible (partial) answer to that question might be: Add a subsection to the 'Information for contributors' section, focusing not on contributors to the code base but on contributors to this wikibook. In that page, there could be a road-map and a list of things that need doing (in case there are any energetic people who want to know what they could do to help).

I am not going to make such far-reaching changes yet, but I would be interested to know if others who work on this book from time to time agree.

CMSMcQ (discuss • contribs) 16:56, 8 February 2017 (UTC)

Should these topics be added to the Getting Started section?
This section of the talk page has been added as a collection point for topics that could or should be added to the Getting Started section. These topics could be added to the table of contents page, but that tends to make the book look more incomplete than it is. Also, in some cases it's not clear how best to shape a topic. It's probably a goo d idea to sign your suggestions.


 * Learning the basics of XForms. Not a tutorial on XForms (at least, not now).  But a tutorial on how to learn XForms, with pointers to tutorials, useful resources, the spec, etc. CMSMcQ (discuss • contribs) 20:59, 11 February 2017 (UTC)
 * Basic development and debugging infrastructure. How to look at the current state of an instance; how to deal with same-origin problems; using XSLTForms on localhost; from file system, ... (All kept simple and non-technical.  No Apache configuration.) CMSMcQ (discuss • contribs) 20:59, 11 February 2017 (UTC)
 * Using XForms within ordinary HTML pages.
 * See Alain Couthures to xsltforms-support 3 May 2012 under the subject line [ANN] script/@type="text/xforms" support in XSLTForms.
 * I'm not sure where this topic belongs.
 * It could go in Getting Started on the theory that it's mostly people starting out who find writing a full XHTML document intimidating and want to have an ordinary HTML document with an XForms island.
 * It could go in Advanced Topics on the grounds that it's a special case for the deployment of XForms; it's useful not just for beginners (in fact, it's not particularly useful for beginners) but for people working in content management systems where the only thing a user gets to specify is part of the content of the  element, not the entire document.
 * CMSMcQ (discuss • contribs) 20:59, 11 February 2017 (UTC)


 * Using the file system with XSLTForms. Every beginner's first thought.  A discussion of what works and what doesn't work, also of the Java applet XSLTForms provides for access to the local file system. CMSMcQ (discuss • contribs) 20:59, 11 February 2017 (UTC)

Should these topics be added to the Advanced Topics section?
This section of the talk page has been added as a collection point for topics that could or should be added to the Advanced (or: Further) Topics section. These topics could be added to the table of contents page, but that tends to make the book look more incomplete than it is. Also, in some cases it's not clear how best to shape a topic.

There may be some topics which belong in a separate Specialized Topics section (in a printed book, I'd make appendices for them); I think the discussion of ways to support PUT falls into this group. CMSMcQ (discuss • contribs) 20:49, 11 February 2017 (UTC)


 * Subforms in XSLTForms. Introduce idea of subforms, illustrate.  Optionally discuss differences between subforms in XSLTForms and subforms in other implementations.  (Which implementations have subforms?  BetterForm, yes.  Orbeon?  EMC? CMSMcQ (discuss • contribs) 21:01, 11 February 2017 (UTC)
 * Datatyping and validation in XSLTForms. Which XSD datatypes does XSLTForms understand out of the box? Which does it not currently know about?  Does XSLTForms understand user-defined types?  If it does at all, how much of them does it understand?
 * Other limits on support for XSD? (For example:  the test suite makes clear that XSLTForms won't load multiple schema documents for the same namespace pointed to from the form.  Will it follow xsd:include and xsd:import links in a schema document?  I assume xsd:override and xsd:redefine are way beyond what one can expect, but I haven't checked.  I may be the only person in the universe of possible XForms users who cares, but in case I'm not ...) CMSMcQ (discuss • contribs) 21:01, 11 February 2017 (UTC)


 * Error diagnosis, error message, user help, hints in XSLTForms. Discussion of errors in user data, not in the form itself.  CMSMcQ (discuss • contribs) 21:01, 11 February 2017 (UTC)0


 * Working with events in XSLTForms
 * The XForms spec quite plausible declines to re-explain things that are laid out in the XML Events spec. But the result is that some readers (I can name at least one) find the description of event handling very clear and easy to follow, but impossible to use in practice.  (I never know which element needs to be the listener, or how to make it the listener, and I've never managed to do anything interesting or useful with events.)
 * In the case of XSLTForms, things are made more complicated by the fact that event-handling tests make up a significant block of red in the test results. So understanding the XForms spec is not enough; one must also know how much of it applies, and how, to XSLTForms.
 * CMSMcQ (discuss • contribs) 21:01, 11 February 2017 (UTC)


 * Server-side support for PUT
 * This is in theory orthogonal to XForms, but in practice it's a huge hurdle for would-be users. A survey of options would be very helpful.  Is WebDAV the most common approach? CMSMcQ (discuss • contribs) 21:01, 11 February 2017 (UTC)


 * Running XSLTForms as a Chrome app (with support for file open/save). See mail to xsltforms-support from Mats Eklund on 7 April 2016 Download action/control (and associated thread)


 * XSLTForms and SVG (generating SVG from user-updateable data and displaying in the page; XForms controls within SVG images [AC to support list, 2 Apr 2012 ''SVG and XForms]]] CMSMcQ (discuss • contribs) 01:39, 12 February 2017 (UTC)