getting-started.md

+# XSweet
+
+## Getting Started
+
+### Documentation
+
+Documentation for XSweet is a work in progress.
+
+We have needs both for testing but even more for documenting, not only XSweet itself but how to run, test and use it. However, resources are short so we also can't let any effort distract us from short/medium-term priorities.
+
+We invite people to create a branch of XSweet in Gitlab wherein you could mess around, documenting what you learn. This would give you control over your own thing without directly impacting our testing/dev cycle; and we could benefit passively.
+
+### Setting Up a Development Environment
+
+So far we have run XSweet in three different environments:
+
+#### 1. Bash Scripts
+
+It is possible to run XSweet via a sequence of calls in a bash script. This is not the most efficient way to run a transformation sequence, but it is very portable, fairly easy to maintain/debug for someone with scripting skills, and as flexible as you need.
+
+Running XSweet this way typically results in a pile of result (output) files (nominally HTML, but syntactically also XML for entry to any next step), one of which is the purported "final output" of the pipeline (which is sometimes a pipeline-of-pipelines). If your main interest is in what comes out and to look back along the chain (to help diagnose problems or lapses), this is very useful.
+
+#### 2. Editoria and INK with Saxon-HE
+
+Within Editoria, the web-based editor under development at Coko, we have run XSweet under INK, our API for a distributed resource/processing architecture, which Editoria works with. Within INK, a call on an XSweet process works as more of a black box pipeline -- one (docx) file goes in, one (HTML) file comes out. Unpacking the docx, intermediate results and all that are maintained behind the scenes, and only exposed if debugging INK is called for (through its interfaces).
+
+In principle, INK can execute anything, as its steps (implemented as ruby gems) work by calling external processes: for XSweet this is again Saxon over a JVM, to achieve the XSLT transformations. The core dependency is [Saxon-HE](http://www.saxonica.com/download/opensource.xml).
+
+#### 3. XProc Pipelines and oXygen Editor
+
+XSweet can be run as a set of XProc pipelines, which very greatly eases development and debugging inasmuch as (most especially end to end) the pipelines can already get a bit long. Using XProc pipelines as wrappers for XSLT sequences is analogous to the "step" in INK (which likewise might encapsulate several transformations) -- but unlike the other approaches, it works well with XSLT IDE (oXygen XML Editor), runs super-fast, and permits easy testing of how the steps relate to one another as well as what each one does on its own. Look at .xpl files in the repo to see the XProc. The XProc processor inside oXygen XML Editor is [XML Calabash](http://xmlcalabach.com).
+
+Although a W3C Recommendation, [XProc](https://www.w3.org/TR/xproc/) is something of an over-the-edge technology, however, so we have not pushed this as a general solution as opposed to XSLT-by-any-other-means. There are many pipelining technologies, even just for XML/XSLT, which makes XSweet extremely flexible, opening future possibilities.
+
+#### Document Testing
+
+For sample documents, testing is being performed against both "actual" documents (by/for the Coko project motivating the activity) and (sometimes "pathological") mockups. But none of them are canonical and our requirements development has been fairly 'agile'. So using your own samples is probably the way to go.
+
+#### Contributing
+
+Contributions to the documentation effort are welcome. Documentation is currently managed within the [GitLab wiki for XSweet](https://gitlab.coko.foundation/wendell/XSweet/wikis/home).
+
+Sign up for access to the GitLab repositories. Use your GitHub account to authenticate through OAuth. Clone the repository for the Wiki.
+
+`git clone git@gitlab.coko.foundation:wendell/XSweet.wiki.git`
+
+The documentation is using [gollum](https://github.com/gollum/gollum), a simple wiki system built on top of Git. (It is possible to run gollum locally, but it is not necessary to install a Ruby development environment locally to install gems and run the application if all you want to do is edit the Markdown files in the wiki repository.)
+
+##### Atom Editor
+
+For those using [Atom Editor](https://atom.io/), install the [Markdown Preview package](https://atom.io/packages/markdown-preview) to edit and preview Markdown files for the documentation effort.