I've also reviewed the tutorials with following comments in addition to Mark's.

Daffodil_Fixed_Values_AveryBibeau.docx

• 'fixed' checking only takes place if validation is enabled during DFDL parse or unparse. That aspect is better covered by a tutorial on validation.
• Because 'fixed' also implies a defaulting behaviour, the checking aspect can not be dealt with in isolation, and needs to be part of a tutorial on default values.

Daffodil_Trimming_AveryBibeau_3.docx

• Mentions textStringJustification but not textNumberJustification or textBooleanJustification or textCalendarJustification
• Doesn't mention 'center' justification
• The 'time' example should use logical integers as the element type, and therefore textNumberJustification and textNumberPadCharacter.
• Should also cover padding as the properties are related and often used together.
• As Mark says, the email header example is a poor one to use, as reading the schema indicates that the spaces are being consumed by the %WSP*; used in the initiators, and not by the trimming properties at all.

Escape_Block_AveryBibeau.docx

• In the DFDL language, defineEscapeScheme is unique in that provides a way of grouping a specific set of related properties, and referring to them, instead of carrying them directly on an object. This is not properly covered.
• The dfdl:escapeSchemeRef is key, but is not mentioned in the text and only appears in the example.
• The name DefaultPropertiesEscapeScheme could be better.
• extraEscapeCharacter should be extraEscapedCharacters and is not described.

Escape_Character_AveryBibeau.docx

• Same comments as above.
• Better to have a single tutorial that covers and contrasts both kinds of escape scheme.

Steve Hanson
Architect, IBM DFDL
Co-Chair, OGF DFDL Working Group
IBM SWG, Hursley, UK
smh@uk.ibm.com
tel:+44-1962-815848
----- Forwarded by Steve Hanson/UK/IBM on 02/06/2014 10:25 -----

From:        Mark Frost/UK/IBM@IBMGB
To:        dfdl-wg@ogf.org,
Cc:        jgarriss@mitre.org
Date:        13/05/2014 16:32
Subject:        Re: [DFDL-WG] DFDL mini-tutorials
Sent by:        dfdl-wg-bounces@ogf.org

---

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@uk.ibm.com

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