Requirements-Rendering Information

From HL7Wiki
Jump to navigation Jump to search

As part of many artifacts, guidance is included that influences how those artifacts are to be rendered in "published form"

Requirement Some artifact elements require manual assignment of sort order to define the order in which those artifacts should be rendered.
  • Often there is a "logical" order of progression to artifacts that aids in the understanding of the entire group of artifacts such that it's important to read about artifact 1 before artifact 3. This order can't necessarily be inferred from other properties of the artifact.
  • In some cases, within a set of artifacts there are some that have a higher degree of importance than others. It is desirable to render these first to ensure that a reader with limited time gets the important information first. The importance can't necessarily be inferred from other properties of the artifact
MIF mif-core-base.xsd/SortKeyOptional/@sortKey

(to do - list where)

Requirement When capturing free-text, the author needs to be able to assert rendering instructions such as bold, italics, bulleted and numbered lists, etc.
Rationale Many textual descriptions can be long and complex, particularly walkthroughs, appendices and stand-alone documents. Users need to have some degree of control over the appearance of their content
MIF xhtml1-strict.xsd (various)

Requirement Overall control over rendered content must remain with the publication process.
Rationale A given artifact may be rendered in multiple locations at many different levels of granularity. Because the context may vary, determinations such as whether a title is "heading level 1" vs. "heading level 3" cannot be made until an artifact is rendered. It cannot be made at authoring time.

Similarly, the overall "style" of the content such as color, font sizes, etc. needs to be controlled by publication to ensure that content is rendered consistently within a given publication.

  • Markup elements related to specific "heading levels" is prohibited
  • Markup elements related to style is tightly constrained to styles pre-defined by the publication committee
  • Markup elements related to "control" such as buttons are prohibited
  • Markup elements related to embedded objects are tightly constrained to those specifically allowed by the publication committee

Requirement Markup needs to allow references to HL7 artifacts and characteristics of them such as "name"
Rationale When creating documentation it's common to need to refer to other artifacts. For example when describing one datatype property, another property might be referenced or when defining an attribute, a contrast statement may be made with another related attribute. However, the names of elements can change over time. Due to the volume of HL7 artifacts and descriptions, updating all artifacts to reflect the new name is challenging and it's common for some to be missed. By using tagged references, it is easier to search for those references and also validate in situations where a referenced item may no longer exist (or may no longer exist with the referenced name).

In addition, HL7 specifications are often published in a navigable hyperlinked format. By referencing items with tags rather than free-text names, it is possible to render those references as hyperlinks allowing the reader to easily navigate to the referenced artifact if desired.

Methodology Many of the custom "object" names and parameters in HL7's markup allow references to other artifacts or elements within those artifacts.