tuxji commented on code in PR #90: URL: https://github.com/apache/daffodil-site/pull/90#discussion_r889749658
########## site/extensions.adoc: ########## @@ -0,0 +1,60 @@ +:page-layout: page +:url-asciidoctor: http://asciidoctor.org +:keywords: plugins layering UDF charset +// /////////////////////////////////////////////////////////////////////////// +// +// This file is written in AsciiDoc. +// +// If you can read this comment, your browser is not rendering asciidoc automatically. +// +// You need to install the asciidoc plugin to Chrome or Firefox +// so that this page will be properly rendered for your viewing pleasure. +// +// You can get the plugins by searching the web for 'asciidoc plugin' +// +// You will want to change plugin settings to enable diagrams (they're off by default.) +// +// You need to view this page with Chrome or Firefox. +// +// /////////////////////////////////////////////////////////////////////////// +// +// When editing, please start each sentence on a new line. +// See https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[one sentence-per-line writing technique.] +// This makes textual diffs of this file useful in a similar way to the way they work for code. +// +// ////////////////////////////////////////////////////////////////////////// + += DFDL Language Extensions in Daffodil + +Daffodil contains numerous extensions to the DFDL v1.0 language. + +Many of these have been, or will be proposed for inclusion in a future version of the DFDL standard. + +This page provides a central starting point for the documentation of these extension features. + +== About Daffodil Plugins + +To provide some new advanced format capabilities such as checksums, compressed or encoded data regions, and user-defined-functions, DFDL schemas sometimes must use Daffodil-specific extensions and incorporate Daffodil plugins that provide the small algorithmic aspects needed by these formats. + +There are 2 kinds of plugins today supported by Daffodil 3.3.0 + +- Layering Transformer (e.g., unzip/zip, verify/recompute checksums) +- User Defined Function (UDF) (e.g., convert mean-sea-level elevation to height-above-ellipsoid) + +There is one additional kind of plugin that will be supported by Daffodil 3.4.0 + +- Character Set Definitions (e.g., a specific 5-bit charset used only by a certain format) + +One needs to think of plugins as being part of the DFDL schema of a format, not part of Daffodil. + +Different DFDL schemas for different kinds of data will need their own such plugins. +Hence the plugins, like the DFDL schema files themselves, are used in applications as part of a specific data-processing flow. + +Keeping in the spirit of DFDL in describing a format declaratively, plugins need to be very small pieces of code (ex: a character set definition should be 10 lines of code.) Review Comment: I think it's fine to break a sentence across multiple lines as long as the next sentence begins on a new line (not immediately after the period punctuating the previous sentence). We break long lines of code, so we should break long sentences as well. ########## site/extensions.adoc: ########## @@ -0,0 +1,60 @@ +:page-layout: page +:url-asciidoctor: http://asciidoctor.org +:keywords: plugins layering UDF charset +// /////////////////////////////////////////////////////////////////////////// +// +// This file is written in AsciiDoc. +// +// If you can read this comment, your browser is not rendering asciidoc automatically. +// +// You need to install the asciidoc plugin to Chrome or Firefox +// so that this page will be properly rendered for your viewing pleasure. +// +// You can get the plugins by searching the web for 'asciidoc plugin' +// +// You will want to change plugin settings to enable diagrams (they're off by default.) +// +// You need to view this page with Chrome or Firefox. +// +// /////////////////////////////////////////////////////////////////////////// +// +// When editing, please start each sentence on a new line. +// See https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[one sentence-per-line writing technique.] +// This makes textual diffs of this file useful in a similar way to the way they work for code. +// +// ////////////////////////////////////////////////////////////////////////// + += DFDL Language Extensions in Daffodil + +Daffodil contains numerous extensions to the DFDL v1.0 language. + +Many of these have been, or will be proposed for inclusion in a future version of the DFDL standard. + +This page provides a central starting point for the documentation of these extension features. + +== About Daffodil Plugins + +To provide some new advanced format capabilities such as checksums, compressed or encoded data regions, and user-defined-functions, DFDL schemas sometimes must use Daffodil-specific extensions and incorporate Daffodil plugins that provide the small algorithmic aspects needed by these formats. + +There are 2 kinds of plugins today supported by Daffodil 3.3.0 Review Comment: Consider ending both this sentence and the following sentence at line 44 with a colon as punctuation. ########## site/extensions.adoc: ########## @@ -0,0 +1,60 @@ +:page-layout: page +:url-asciidoctor: http://asciidoctor.org +:keywords: plugins layering UDF charset +// /////////////////////////////////////////////////////////////////////////// +// +// This file is written in AsciiDoc. +// +// If you can read this comment, your browser is not rendering asciidoc automatically. +// +// You need to install the asciidoc plugin to Chrome or Firefox +// so that this page will be properly rendered for your viewing pleasure. +// +// You can get the plugins by searching the web for 'asciidoc plugin' +// +// You will want to change plugin settings to enable diagrams (they're off by default.) +// +// You need to view this page with Chrome or Firefox. +// +// /////////////////////////////////////////////////////////////////////////// +// +// When editing, please start each sentence on a new line. +// See https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[one sentence-per-line writing technique.] +// This makes textual diffs of this file useful in a similar way to the way they work for code. +// +// ////////////////////////////////////////////////////////////////////////// + += DFDL Language Extensions in Daffodil Review Comment: That other page talks about DFDL extensions while this page talks about extensions to Daffodil schemas (slightly more general). Probably better to merge that page into this page than the other way around. -- 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]
