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
>
>