exist-development

[Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Dan M. <dan...@gm...>]

Here is a link to a very early DRAFT of "A Beginners Guide to XRX".

http://www.syntactica.com/training/xrx/beginners/index.html

You will find links to:

   - the HTML and PDF versions of the beginner's guide
   - the DocBook source
   - a zip file of the source code
   - a link to a the demo CRUDS app running on the Syntactica web server


I have just used the default oXygen DocBook rendering and I am still playing
around with the image scaling and formatting.  Any suggestions on DocBook
formatting or options would be appreciated.

My real questions are what are the critical "learning points" of getting new
people up and running using eXist and XRX to build simple CRUDS
applications?  What are the learning barriers we need to get people over?
Will very simple templates and examples help?  How can we combine our
DocBook versions with the WikiBooks?  How can we move to a "topic-based"
system that will work with an overall search engine to help people quickly
find the example code they need to solve a specific tasks?

Thanks! - Dan

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Wolfgang M. <wol...@ex...>]

Hi Dan,

> Here is a link to a very early DRAFT of "A Beginners Guide to XRX".

Great. I think the document explains things at the right level of
complexity. Not too easy, not too difficult. Maybe it would be good if
some of our rather non-technical users could go through the text and
tells us where they have questions.

> I have just used the default oXygen DocBook rendering and I am still playing
> around with the image scaling and formatting.  Any suggestions on DocBook
> formatting or options would be appreciated.

The stylesheet we use for the rest of the documentation is
webapp/stylesheets/db2xhtml.xsl (or
webapp/stylesheets/db2html.xsl). It automatically applies the standard
eXist design and should cover most of the docbook tags.

> My real questions are what are the critical "learning points" of getting new
> people up and running using eXist and XRX to build simple CRUDS
> applications?  What are the learning barriers we need to get people over?

I think the major problem is that eXist provides several ways to
approach XRX development. The first question of a new user might be:
where do I put my XQuery files? You answer this question by
establishing a number of conventions. This is good. I think the text
should indeed guide the user by presenting clear decisions. However,
we may need to mention that there can be other approaches, e.g. if you
are using eXist within your own web application besides other
components.

URL mapping and rewriting will be another important topic we may need
to deal with. Once they have their basic application setup, their next
question probably is how to map simpler URLs to the CRUD operations.

> Will very simple templates and examples help?  How can we combine our
> DocBook versions with the WikiBooks?  How can we move to a "topic-based"
> system that will work with an overall search engine to help people quickly
> find the example code they need to solve a specific tasks?

Could we export the wikibook contents to XML and set up a search page
within eXist which can directly query for topics, titles, examples and
the like?

Wolfgang

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Adam R. <ad...@ex...>]

> Could we export the wikibook contents to XML and set up a search page
> within eXist which can directly query for topics, titles, examples and
> the like?

I think Chris Wallace might be interested in this. He was looking for
a better platform for the Wikibook content, where he could display the
source of an XQuery as part of an example on a page without having to
copy and paste the code and keep both maintained.

I suggested that Atomic might be a good solution with a few minor
additions/modifications for his needs.


> Wolfgang
>
> ------------------------------------------------------------------------------
> Download Intel® Parallel Studio Eval
> Try the new software tools for yourself. Speed compiling, find bugs
> proactively, and fine-tune applications for parallel performance.
> See why Intel Parallel Studio got high marks during beta.
> http://p.sf.net/sfu/intel-sw-dev
> _______________________________________________
> Exist-development mailing list
> Exi...@li...
> https://lists.sourceforge.net/lists/listinfo/exist-development
>



-- 
Adam Retter

eXist Developer
{ United Kingdom }
ad...@ex...
irc://irc.freenode.net/existdb

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Wolfgang M. <wol...@ex...>]

> I suggested that Atomic might be a good solution with a few minor
> additions/modifications for his needs.

Yes, that's one of the main features of Atomic. But we could also
extend our docbook stylesheets to do the same magic: show the source
code of an XQuery and at the same time the results of its execution.
We would just need to pass the document through an XQuery which
expands a certain set of tags before passing the content on to the
final stylesheet. This is easy to achieve through a controller
pipeline (or xproc, if you prefer).

Wolfgang

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Chris W. <Chr...@uw...>]

Yes that's more or less what I had in mind  My model in this is Knuths work with Literate Programming. http://en.wikipedia.org/wiki/Literate_programming

The longer Wikibook examples attempt to explain the role of the code in an order which makes sense to the reader - which is not the order or level of detail required of the code.  Implementations of Knuth's idea start from a single source document, from which both the literary explanation and the code is generated.  I'd prefer an approach in which the literary explanation contained references to the XQuery scripts and included the text, suitably formatted for the specified language in the generated HTML 

So the extensions would be something like:

<include lang="xquery" source="/db/Wiki/lib/geo.xqm" function="latlong-2-mercator(,,,)"/>

or 

<include lang="xquery" source="/db/Wiki/geo/map.xg" start="10" end="20"/>

or 

<include lang="xml" source="/db/Wiki/dashboard/config.xml"/>

or 

<include lang="xquery" execute="yes">
 
  ("a","b","c")[last()

</include>

as well as simple links to execute a URL relative to a document base - this a  problem in the Wikibook where all the URLS are absolute

BTW I assume the AtomicWiki uses versioning to maintain a version history?

Chris
______________________________________
From: Wolfgang Meier [wol...@ex...]
Sent: 25 March 2010 16:32
To: Adam Retter
Cc: da...@da...; exi...@li...; Henry Neils; Chris Wallace
Subject: Re: [Exist-development] First draft of "A Beginners Guide to XRX on    eXist"

> I suggested that Atomic might be a good solution with a few minor
> additions/modifications for his needs.

Yes, that's one of the main features of Atomic. But we could also
extend our docbook stylesheets to do the same magic: show the source
code of an XQuery and at the same time the results of its execution.
We would just need to pass the document through an XQuery which
expands a certain set of tags before passing the content on to the
final stylesheet. This is easy to achieve through a controller
pipeline (or xproc, if you prefer).

Wolfgang

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Joe W. <jo...@gm...>]

Hi Dan,

The Beginners XRX file is excellent.  I made some edits as I read
through it to get a sense of how you're structuring the tutorial.  I
haven't addressed your "big" questions yet, but I'm attaching the
edited DocBook file here.  I focused solely on the text and not the
graphics.  Please take my edits with a grain of salt, and
accept/reject the diffs as you see fit.  I've also spelled out some
comments here:

1. I did my editing in oXygen's Author mode, which worked very nicely.
 Did you know that oXygen has a spell checker?  I figured out how to
turn it on: Preferences > Spell Check > Automatic Spell Check.  It
lets you add words to its dictionary, and underlines misspelled words
very clearly.  This is a great feature that we should all make use of
in editing DocBook content!

2. I removed this from the XQuery intro paragraph:

"One caution. There are some things that are prohibited in XQuery that
you should be aware of. In general, XQuery variables are only set once
but never changed. So functions like let $x := $x + 1 are not
permitted. There are also restrictions on what can be done inside
FLOWR statements. We will illustrate these in examples later in the
beginner guides."

I removed it because I thought it doesn't need to be in the 'intro to
XQuery' statement.  Also, let $x := $x+1 is a valid XQuery statement:

let $x := 1
let $x := $x + 1
return $x

... returns 2, proving that the value of variables can change.  What
is the point you're trying to convey?

3. I tried to make the code samples consistent in indents (4 spaces)
and linebreaks (e.g. 1 linebreak between the xquery declaration and
the prolog).  I removed the linebreaks at the beginning and end of
code samples, since it seemed to me that this was a presentation duty
that CSS should perform.  I also standardized the style of comments to
make comments like "this logs us in as admin..." into "log in as
admin".

4. I tried to standardize the final commas in lists, e.g. "a, b, c,
and d" instead of "a, b, c and d".  Both styles are valid, but I
consider the former clearer for readers.

5. I noticed that CDATA was difficult to insert in the code samples.
Does anyone have any suggestions on this?

Joe


On Wed, Mar 24, 2010 at 9:04 PM, Dan McCreary <dan...@gm...> wrote:
> Here is a link to a very early DRAFT of "A Beginners Guide to XRX".
>
> http://www.syntactica.com/training/xrx/beginners/index.html
>
> You will find links to:
>
> the HTML and PDF versions of the beginner's guide
> the DocBook source
> a zip file of the source code
> a link to a the demo CRUDS app running on the Syntactica web server
>
> I have just used the default oXygen DocBook rendering and I am still playing
> around with the image scaling and formatting.  Any suggestions on DocBook
> formatting or options would be appreciated.
>
> My real questions are what are the critical "learning points" of getting new
> people up and running using eXist and XRX to build simple CRUDS
> applications?  What are the learning barriers we need to get people over?
> Will very simple templates and examples help?  How can we combine our
> DocBook versions with the WikiBooks?  How can we move to a "topic-based"
> system that will work with an overall search engine to help people quickly
> find the example code they need to solve a specific tasks?
>
> Thanks! - Dan
>
> ------------------------------------------------------------------------------
> Download Intel&#174; Parallel Studio Eval
> Try the new software tools for yourself. Speed compiling, find bugs
> proactively, and fine-tune applications for parallel performance.
> See why Intel Parallel Studio got high marks during beta.
> http://p.sf.net/sfu/intel-sw-dev
> _______________________________________________
> Exist-development mailing list
> Exi...@li...
> https://lists.sourceforge.net/lists/listinfo/exist-development
>
>

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[Wolfgang M. <wol...@ex...>]

> 5. I noticed that CDATA was difficult to insert in the code samples.
> Does anyone have any suggestions on this?

I think you have to switch to the "Text" mode in Oxygen and enter the
CDATA manually. I could not find any shortcuts for this.

We use the following conventions for the syntax highlighting in
eXist's standard stylesheets:

XQuery code example:

<example>
  <title>A Simple Query</title>
  <programlisting language="xquery"><![CDATA[for $m in
//SPEECH[ft:query(., "boil bubble")]
order by ft:score($m) descending
return $m]]></programlisting>
</example>

XML code:

<example>
  <title>collection.xconf fragment</title>
  <programlisting><markup><![CDATA[<lucene>
    <text qname="p"/>
    <text qname="note"/>
    <ignore qname="note"/>
</lucene>]]></markup>
</programlisting>

Single line of XQuery:

<synopsis language="xquery">//p[ft:query(., "note")]</synopsis>

Using those elements should give you nicely rendered code.

Wolfgang

Re: [Exist-development] First draft of "A Beginners Guide to XRX on eXist"

[George C. B. <ge...@ox...>]

Hi,

On 3/28/10 10:32 AM, Wolfgang Meier wrote:
>> 5. I noticed that CDATA was difficult to insert in the code samples.
>> >  Does anyone have any suggestions on this?
> I think you have to switch to the "Text" mode in Oxygen and enter the
> CDATA manually. I could not find any shortcuts for this.

In oXygen in Author mode if you press Enter you get the list with 
proposals. At the end there are some special entries, rendered with 
italic style, one of them is /cdata/ with the annotation [Insert CDATA]. 
If you select that then a CDATA section will be inserted. Note that you 
can type to filter the proposals, so basically to quicly inser a CDATA 
section in a DocBook document you can use

Enter
Type cd (you will get cdata as the only proposal)
Enter

Best Regards,
George
-- 
George Cristian Bina
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com