mbeckerle commented on code in PR #204:
URL: https://github.com/apache/daffodil-site/pull/204#discussion_r2549928805
##########
site/dfdl-training.md:
##########
@@ -0,0 +1,274 @@
+---
+layout: page
+title: DFDL Training
+group: nav-right
+---
+<!--
+{% comment %}
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to you under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+{% endcomment %}
+-->
+
+## Table of Contents
+{:.no_toc}
+<!-- The {: .no_toc } excludes the above heading from the ToC -->
+
+1. yes, this is the standard Jekyll way to do a ToC (this line gets removed)
+{:toc}
+<!-- note the above line {:toc} cannot have whitespace at the start -->
+
+# Introduction
+
+There are a few paths to take in order to learn DFDL depending on your goals
and background.
+This page provides resources allowing you to learn by working your way through
labs that
+gradually introduce DFDL concepts, or you can plunge right into well-crafted
DFDL schemas for
+basic data formats, and gradually work up to more complex ones.
+
+There is a general [Overview Presentation about DFDL](
+{{ site.data.links.slides.overviewDFDL}}) with sections about:
+- Motivation: Why we need DFDL
+- Introduction to DFDL - including a tiny example
+- Larger Examples: CSV, PCAP, MIL-STD-2045
+
+The remaining sections are perhaps less interesting for DFDL beginners.
+- Where to get DFDL Schemas
+- Apache Daffodil - What is in it
+- Example of using Daffodil's Java API (yes it's "Hello World!")
+
+Reading [Section 1]({{ site.data.links.dfdlSpec.intro}})(the introduction) of
the
+[DFDL Specification]({{ site.data.links.dfdlSpec.specStart}})
+is also a basic introduction to DFDL.
+
+# Prerequisites
+
+There are several things that you need to be familiar with to learn DFDL.
+These include:
+- XML - Extensible Markup Language
+- XML Schema (aka XSDL or XSD)
+- Basic Data Format Concepts
+- DFDL Basic Terminology
+
+### XML - Extensible Markup Language
+
+Daffodil supports both JSON and XML, but the learning/training materials are
very biased towards
+using XML.
+
+- [{{ site.data.links.xml.introWho}} XML Tutorial](
+{{ site.data.links.xml.introXML}}) - Gives a basic
+introduction to XML.
+- [Our Slides: Introduction to XML]({{ site.data.links.slides.introXML}}) -
Provides a deeper dig
+ into XML use as a data language and some of the challenges with escaping,
CRLF/LF, NUL, and
+ whitespace.
+
+### XML Schema (aka XSD or XSDL)
+
+DFDL uses a subset of the XML Schema Definition Language (XSDL or XSD) to
express
+the structure of data, meaning the field names,
+their order, and nesting of hierarchical structure.
+This means that _a DFDL Schema **is** an XML Schema_.
+
+If you are familiar with the notion of a
+[_grammar_ or _BNF_]({{ site.data.links.reference.bnf}}),
+XML Schema is conceptually similar.
+It is more verbose, but provides standardized places to add _annotations_ to
the schema
+which allows DFDL to add the data format information onto the schema in a
standard way.
+
+- [{{ site.data.links.xml.introWho}} XML Schema Tutorial](
+{{ site.data.links.xml.introXSD}}) - Gives the basics about XML Schema.
+ - _Ignore anything about DTD, which are an older kind of schema for XML.
+ DFDL does not use DTDs and in fact prohibits their use._
+- [Our Slides: Introduction to XML Schema]({{
site.data.links.slides.introXSD}}) - Deeper
+ introduction giving more of the motivation for why DFDL is built on top of
XML Schema.
+
+### Basic Data Format Concepts
+
+You will need to be familiar with these concepts:
+- bit
+- byte
+- character set - ASCII, Unicode, UTF-8.
+ Also called a character _encoding_.
+- [byte order - big-endian and little-endian](
+{{ site.data.links.referece.endianness}})
+- [hexadecimal (aka hex)]({{ site.data.links.reference.hex}})
+
+### DFDL Basic Terminology
+
+DFDL uses these terms often:
+- Native - the raw data format of the input to a DFDL parse process
+- Infoset - the output representation of the parsed data. For learning
purposes we'll assume
+ the Infoset is represented in XML.
+- Parse - to convert data from native format to an infoset
+- Unparse - The preferred term for the opposite of parse: to convert data from
an infoset back into
+ native form.
+ This is often called _serialization_ or _marshalling_ in other non-DFDL
contexts.
+- DFDL Processor - either a DFDL Parser or DFDL Unparser
+- Well-Formed - data is well-formed if a DFDL Parser can successfully produce
an infoset. Note
+ that well-formed data may be _invalid_.
+- Valid - data (or its parsed infoset) is valid if it is both well-formed and
can be validated
+ against an XML Schema (i.e., the DFDL schema). Valid means an infoset is
_Schema Valid_.
+
+There is also a [Glossary of DFDL Terms](
+{{ site.data.links.dfdlSpec.glossary}}
+) in the DFDL Specification.
+
+# Tools Needed for Hands-On Training
Review Comment:
Yes, I'll move this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
