This is an automated email from the ASF dual-hosted git repository.
slawrence pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/daffodil-sbt.git
The following commit(s) were added to refs/heads/main by this push:
new a456c8f Improve DaffodilBinInfo parameter documentation
a456c8f is described below
commit a456c8f418f2a8b724eb3a0fdbce2468a8c6887f
Author: Steve Lawrence <[email protected]>
AuthorDate: Fri Oct 25 08:40:43 2024 -0400
Improve DaffodilBinInfo parameter documentation
For each of the parameters of a DaffodilBinInfo, this adds more detailed
descriptions and examples, making it more clear what is expected of each
parameter and what it affects.
This also moves it out of a table. Although the table was succinct, it
really does not give enough space for detailed descriptions and examples
that we need.
Closes #65
---
README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 65 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index fed21d9..c9f06d1 100644
--- a/README.md
+++ b/README.md
@@ -61,14 +61,71 @@ This plugin adds the ability to create and publish saved
parsers of a schema.
For each saved parser to generate, add an entry to the
`daffodilPackageBinInfos` setting. This setting is a `Seq[DaffodilBinInfo]`,
where each element in the sequence defines information to create a saved parser
-with the following parameters:
-
-|Name |Type |Reqiured | Description |
-|--------|-----------------|---------|-------------|
-|schema |`String` |yes |Resource path to the main schema |
-|root |`Option[String]` |no |Root element in the schema. If `None`,
uses the first element in the schema |
-|name |`Option[String]` |no |If `Some`, includes value in the jar
classifier, useful to distinguish saved parsers |
-|config |`Option[File]` |no |Path to a configuration file used during
compilation |
+with parameters describe below.
+
+#### DaffodilBinInfo Parameters
+
+##### schema
+
+Type: `String`
+
+Resource path to the main schema. Since this is a resource path it must start
+with a `/` and exclude path elements like `src/main/resources`.
+
+Example:
+
+```scala
+schema = "/org/example/xsd/schema.dfdl.xsd"`
+```
+
+##### root
+
+Type: `Option[String]`
+
+Root element in the schema used for parsing/unparsing. If `None`, uses the
+first element found in the main schema. Defaults to `None` if not provided.
+
+Example:
+```scala
+root = Some("fileOfRecords")
+```
+
+##### name
+
+Type: `Option[String]`
+
+If defined, includes the value in the jar classifier. This is required to
+distinguish multiple saved parsers if multiple `DaffodilBinInfo`'s are
+specified. Defaults to `None` if not provided.
+
+Example:
+```scala
+name = Some("file")
+```
+
+##### config
+
+Type: `Option[File]`
+
+Path to a configuration file used during compilation, currently only used to
+specify tunables. If specified, it should usually use SBT settings to create
+the path. Defaults to `None` if not provided.
+
+Example:
+
+If the configuration file is in `src/main/resources/`, then use:
+
+```scala
+config = Some(resourceDirectory.value / "path" / "to" / "config.xml")
+```
+
+If the configuration file is in the root of the SBT project, then use:
+
+```scala
+config = Some(baseDirectory.value / "path" / "to" / "config.xml")
+```
+
+#### Saved Parser Examples
An example of this settings supporting two roots looks like this:
