[DFDL-WG] DFDL mini-tutorials

Tue May 13 11:31:27 EDT 2014

Hi All,

I've had a read over these mini-tutorials, and think they're a great intro 
to specific features. In particular the style is clear and brief, and 
formatting is readable and attractive.

It'd be great to weave these into the existing 'lessons' available at 
http://www.ogf.org/dfdl/. That could be an opportunity to polish the 
presentation of the lessons :
existing lessons are not very high-profile in web searches (perhaps due to 
being pdfs linked only in the sidebar of the ogf site). A separate section 
with an introduction (and html content?) could help
some cross-links between the lessons and tutorials would be handy - eg. 
lesson 4 covers fixed-length data, where trimming is often useful
a little colour and formatting as used in these tutorials aids readability
these tutorials use an XML format for presenting logical infosets, where 
as the lessons use a more generic style without xml tags. I wonder if 
using an XML style presentation might confuse some readers that an infoset 
"is" XML or the purpose of DFDL is to create XML?

w3schools is an example of a tutorial style I find very effective : 
http://www.w3schools.com/schema/schema_intro.asp

Below are a few specific points that came to mind in each of the 
mini-tutorials - 

Daffodil_Fixed_Values_AveryBibeau.docx
discussion of schema vs. dfdl properties would be useful (explain why 
'fixed' is not in the dfdl namespace)
could also cover the defaulting behaviour of xs:fixed (it works like 
xs:default), which makes it more powerful than an equivalent enumeration 
facet with a single value.

Daffodil_Trimming_AveryBibeau_3.docx
email header example is a little confusing as it uses  %WSP*; in 
dfdl:initiator, to consume unwanted whitespace, when the tutorial is about 
padding/trimming

Escape_Block_AveryBibeau.docx
cross ref to escape character tutorial would be useful when published
"Escaping is a useful capability for using alternative data representation 
that includes the separator character"
- more generally, all in-scope markup including separators
- being more explicit might help some readers : that escaping is necessary 
to represent characters in logical values that would otherwise be 
interpreted as markup
CSV is a good real-world example that could be included. 

Escape_Character_AveryBibeau.docx
cross ref to escape block tutorial would be useful when published
"Escape characters can be used to essentially ignore the following 
separator character in an element."
- more generally, all in-scope markup including separators
- being more explicit might help some readers : that escaping is necessary 
to represent characters in logical values that would otherwise be 
interpreted as markup
"defineEscapeScheme is required to create properties related to escaping. 
This definition exists outside of the default properties schema."
- I'm not clear what "outside default properties schema" means here

Regarding possible future topics, I'd suggest leaving 
inputValueCalc/outputValueCalc for later as these aren't yet available in 
the IBM implementation.

Regards,
Mark

Mark Frost 
 IBM United Kingdom

Software Engineer
 Hursley Park
IBM DFDL, IBM Integration Bus
 Winchester

 SO21 2JN

Phone:
+44 (0)1962 817009
 England

e-mail:
frostmar at uk.ibm.com

From:   "Cranford, Jonathan W." <jcranford at mitre.org>
To:     "dfdl-wg at ogf.org" <dfdl-wg at ogf.org>, 
Cc:     "Garriss Jr., James P." <jgarriss at mitre.org>
Date:   15/04/2014 16:30
Subject:        [DFDL-WG] DFDL mini-tutorials
Sent by:        dfdl-wg-bounces at ogf.org

DFDL Working Group,

Attached are four mini-tutorials written by Avery Bibeau, a high school 
student. James Garriss of MITRE is mentoring him on a school project which 
includes writing tutorials for DFDL.

The idea is that these mini-tutorials could be folded into tutorials in 
the future more in line with the existing DFDL tutorials at 
www.ogf.org/dfdl.  Avery is contributing these mini-tutorials to the 
Working Group with the hope that he would be credited in the tutorials.

Any feedback would be appreciated.

Also, below is a list of topics he's planning to work on.  If you see 
topics that aren't implemented in either of the implementations, please 
let us know, as he is only trying to write tutorials on features that he 
can test in the existing implementations.
* asserts
* discriminators
* input value calculations

He had planned to do a mini-tutorial on default values, but had problems 
testing his examples in both implementations because apparently support 
for default values is not quite implemented yet.

Thanks in advance,

--
Jonathan W. Cranford 
Senior Information Systems Engineer
The MITRE Corporation (http://www.mitre.org)

[attachment "Daffodil_Fixed_Values_AveryBibeau.docx" deleted by Mark 
Frost/UK/IBM] [attachment "Escape_Block_AveryBibeau.docx" deleted by Mark 
Frost/UK/IBM] [attachment "Escape_Character_AveryBibeau.docx" deleted by 
Mark Frost/UK/IBM] [attachment "Daffodil_Trimming_AveryBibeau_3.docx" 
deleted by Mark Frost/UK/IBM] --
  dfdl-wg mailing list
  dfdl-wg at ogf.org
  https://www.ogf.org/mailman/listinfo/dfdl-wg

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20140513/cf603106/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 360 bytes
Desc: not available
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20140513/cf603106/attachment-0001.gif>