WIP

Author: douwe

README.Rmd

@@ -48,13 +48,13 @@ data <- read_data(datafile, guidefile)
 
 The output of the `read_data()` function is a list object the format of which is determined for a large part by the design of the data guide.
 
-## Details
+## How it works
 
-### How it works
+When you design a template spreadsheet file for data reporting and analysis you also create a *data guide* file that specifies the structure and location of the data in the template. Examples of a template with data and of a data guide are provided in the package (`system.file("extdata", "example_data.xlsx", package = "excelDataGuide")` and `system.file("extdata", "example_guide.yml", package = "excelDataGuide")`).
 
-When you design a template Excel file for data reporting and analysis you also create a *data guide* file that specifies the structure and location of the data in the template. If you design the template carefully you can use the same data guide for several versions of the template. That is, as long as the location of the indexed data does not change, you can use the same data guide for different versions of the template. You can specify the compatible version of the templates in the *data guide*. The package will check compatibility. Clearly, you should use versioned data templates, and  hence, a required field in a template is its version number. An example of a template with data is provided in the package (`system.file("extdata", "example_data.xlsx", package = "excelDataGuide")`).
+Once you have entered the data and metadata in a template you can use the `read_data()` function in the package to extract the data into R with a single command. The package will check and coerce the data types to the required formats.
 
-Once you have entered the data and metadata in a template you can use the package to extract the data into R. The package will check and coerce the data types to the required formats.
+Details about the data guide format and how to write one as well as about how to design a template can be found in the package vignettes.
 
 ### Data guide
 

data-raw/excelguide_schema.cue

@@ -4,14 +4,20 @@
 // This schema validates Excel template guide files that describe how to extract
 // data from Excel workbooks with specific template formats.
 
-// Top-level required fields
+// REQUIRED FIELDS
+// Versions of guide and template
 "guide.version"!:        #Version
 "template.name"!:        string
 "template.min.version"!: #Version
 "template.max.version"!: #Version | null
-"plate.format"!:         #Plateformat
+// Plate format
+"plate.format"!: #Plateformat
+// Locations
 "locations"!: [...#Location]
-"translations": [...#Translation]
+
+// OPTIONAL FIELDS
+// Optional field translations
+"translations"?: [...#Translation]
 
 // Optional field added by validate_and_sign.sh after successful CUE validation.
 // Format: sha256:<64 lowercase hex characters>
@@ -28,6 +34,7 @@
 // inside a for expression, which causes a "reference not found" error at vet time.
 // This constraint is enforced at runtime by check_guide() in R/guide.R instead.
 
+// DEFINITIONS
 // Version constraint: must be in major.minor format (e.g., "1.0", "2.3")
 #Version: =~"^\\d+\\.\\d+$"