Documentation for AddElement, Logical, and Resource

[cmoesel]

Documentation for the new logical model and resource capabilities.

Because AddElement rule has so many possible variations, I struggled w/ the sections defining possible syntaxes. I've very open to suggestions there (as long as they are consistent w/ the approach to syntax already practiced in the spec.

I also am not sure what formatting style we want to take in the examples. Most notably, should we try to keep AddElement rules to a single line when possible? Or should we always put the definition on a newline? Or should we always put short and definition on a newline? What we do may influence the style of others. The current PR tries to keep it to one line except when that is clearly too long.

Keeping to one line at all times:

Logical:        EmergencyVehicle
Title:          "Emergency Vehicle"
Description:    "An emergency vehicle, such as an ambulance or fire truck."
* identifier 0..* SU Identifier "Identifier(s) of the vehicle" "Vehicle identifiers may include VINs and serial numbers."
* make 0..1 SU Coding "The vehicle make" "The vehicle make, e.g., Chevrolet."
* make from EmergencyVehicleMake (extensible)
* model 0..1 SU Coding "The vehicle model" "The vehicle model, e.g., G4500."
* model from EmergencyVehicleModel (extensible)
* year 0..1 SU positiveInteger "Year of manufacture" "The year the vehicle was manufactured"
* servicePeriod 0..1 Period "When the vehicle was in service" "Start date and end date (if applicable) when the vehicle operated."
* operator 0..* Reference(Organization or Practitioner or PractitionerRole) "The operator" "The organization or persons repsonsible for operating the vehicle"
* device 0..* Reference(Device) "Devices on board" "Devices on board the vehicle."

Always putting definition on its own line:

Logical:        EmergencyVehicle
Title:          "Emergency Vehicle"
Description:    "An emergency vehicle, such as an ambulance or fire truck."
* identifier 0..* SU Identifier "Identifier(s) of the vehicle"
    "Vehicle identifiers may include VINs and serial numbers."
* make 0..1 SU Coding "The vehicle make"
    "The vehicle make, e.g., Chevrolet."
* make from EmergencyVehicleMake (extensible)
* model 0..1 SU Coding "The vehicle model"
    "The vehicle model, e.g., G4500."
* model from EmergencyVehicleModel (extensible)
* year 0..1 SU positiveInteger "Year of manufacture"
    "The year the vehicle was manufactured"
* servicePeriod 0..1 Period "When the vehicle was in service"
    "Start date and end date (if applicable) when the vehicle operated."
* operator 0..* Reference(Organization or Practitioner or PractitionerRole) "The operator"
    "The organization or persons repsonsible for operating the vehicle"
* device 0..* Reference(Device) "Devices on board"
    "Devices on board the vehicle."

Always putting short and definition on their own lines:

Logical:        EmergencyVehicle
Title:          "Emergency Vehicle"
Description:    "An emergency vehicle, such as an ambulance or fire truck."
* identifier 0..* SU Identifier
    "Identifier(s) of the vehicle"
    "Vehicle identifiers may include VINs and serial numbers."
* make 0..1 SU Coding
    "The vehicle make"
    "The vehicle make, e.g., Chevrolet."
* make from EmergencyVehicleMake (extensible)
* model 0..1 SU Coding
    "The vehicle model"
    "The vehicle model, e.g., G4500."
* model from EmergencyVehicleModel (extensible)
* year 0..1 SU positiveInteger
    "Year of manufacture"
    "The year the vehicle was manufactured"
* servicePeriod 0..1 Period
    "When the vehicle was in service"
    "Start date and end date (if applicable) when the vehicle operated."
* operator 0..* Reference(Organization or Practitioner or PractitionerRole)
    "The operator"
    "The organization or persons repsonsible for operating the vehicle"
* device 0..* Reference(Device)
    "Devices on board"
    "Devices on board the vehicle."

Now that I've seen the comparison directly, I kind of like the last option (short and definition on their own lines), but I'll leave it as-is for now to get your feedback.

[joepaquette]

Regarding your question on formatting examples... I don't have a strong opinion one way or another since users are free to manage whitespace as desired. That said, if I had to pick one, I'd probably pick the middle option where the main definition is on one line and the definition indented underneath. This introduces some visual separation among AddElementRules while not making the example too long. But again, I'm fine with any of the options.

[cmoesel]

Fixed the two issues reported by @joepaquette. Thanks, Joe!

Will wait on changing overall format of Logical/Resource examples until @markkramerus weighs in on the topic.

[cmoesel]

I'll fix the conflicts now.