SDPi File Organization Scheme

SDPi File Organization Scheme

Table of Contents

• Considerations for Determining the SDPi Supplement File Organization
• SDPi File Organization
• File Naming Conventions
• File Baseline Section Numbering Challenge
• File Types and Examples

Considerations for Determining the SDPi Supplement File Organization

In order to develop a consistent approach for organizing the SDPi Supplement files, various considerations were weighed, including:

1. Current approaches for other recently published IHE TF profiles and supplements (esp. from ITI)

2. Factoring in approaches for markdown-based sources, both that are a single "long" supplement file as well as profiles that are published using the FHIR IG Publisher (whether or not they are FHIR-based profiles)

3. Logical organization based on the SDPi subject matter / content

4. Required organization to support AsciiDoc multi-file specification (input content & output HTML) processing

5. Co-working facilitation (e.g., editors working in parallel on subsections of the specification, such as a gateway actor logic); See the wiki article: Gemini Program Coordination & Co-Working Spaces

And more …​ but that was a good starting-point list!

After reviewing current IHE state-of-the-art, and given the previous Gemini SES+MDI program decision to use AsciiDoc (See wiki article Crafting AsciiDoc-based SDPi Supplement Content), the team settled on the file organization and naming conventions detailed in the sections below.

Warning

The organization and conventions below are not "cast in stone" but they they do represent the starting point for driving to SDPi 1.0. This article will be updated along the way as changes are identified. For example, the folders on the graphic above may include subfolders to support tighter integration of content and cleaner organization, such as /volume2/tf2-dev-23/.adoc content files.

For more detail about the organization of content within the AsciiDoc files, see the wiki article: IHE Technical Framework / SDPi Content in AsciiDoc

SDPi File Organization

The following graphic details the general file structure for the SDPi supplement specification content:

Figure 1. A SDPi File Organization

As explained in the blue next to each folder, the root folder in the Github repository is:

sdp-fhir/SDPi_Supplement/

It was decided to take this approach, namely collecting everything related to the SDPi supplement specification - from source content to support files to automation to generated output - as a subfolder in the existing repository since the development group is already familiar with and actively using the same program repository.

Alternatively, a specific repository could have been created solely for the profiles (e.g., ihe-sdpi or dev-sdpi), as is the general convention that has evolved within IHE; however, that convention evolved long after use of the repository for persisting everything related to the Gemini SES+MDI (SDC/SDPi+FHIR) program. If necessary, given that everything needed to produce the supplement is contained in this repository subtree, it can be migrated in the future to a new repository without too much effort.

Note	"volume0" may also be added if needed, as well as subfolders, as mentioned above

Github "Pages" note - Currently the handoff from the domain (here DEV) development team of the rendered HTML files to IHE Publications team happens through the Github Pages capability (see Github Pages documentation for more information). Before sending the SDPi 1.0 HTML to IHE Publications, the rendered content in the sdpi-supplement folder may need to be integrated with the DEV.SDPi Pages settings to enable moving it to the ihe.github.io site for DEV domain interal review and public comment review. If so, the work effort should be relatively straightforward.

File Naming Conventions

For consistency, the following GENERAL file naming conventions shall apply:

1. All Lowercase (not mixed, not all upper)

2. Dashes (not underscores, not periods, etc.)

   1. Exception would be the integration of file baseline section numbering (e.g., tf3-ch-8.2.8-biceps-content.adoc) - see Baseline Section Numbering below

   2. Underscores may be used in some folder names (Note: this also breaks the "all lowercase" convention above)

3. No special characters (ampersands, em dashes, plus signs, etc.)

4. File extension is .adoc (not .asciidoc)

Some examples might be helpful!

SDPi File Naming Examples

tf1-ch-10-sdpi-p.adoc
tf1-ch-c-use-cases.adoc
tf2-dev-23.adoc
tf2-ch-b-gateways.adoc
tf2-ch-b-gateway-V2.adoc
tf3-ch-8.2.8-biceps-content.adoc

See File Types and Examples below for more detailed information.

File Baseline Section Numbering Challenge

As covered in the related wiki article, IHE Technical Framework / SDPi Content in AsciiDoc, since the SDPi supplement is intended to eventually be integrated into the IHE DEV FT (Final Text) Technical Framework (containing all the IHE DEV profile specifications), the section numbering is not contiguous and is allocated and managed by the IHE DEV TPM & Team.

For example, the Volume 1 SDPi-P (Plug-and-Trust) profile is allocated as section 10. This is it’s "baseline" section number. Therefore, the AsciiDoc file containing the Volume 1 SDPi-P specification includes this baseline section number, namely tf1-ch-10-sdpi-p.adoc.

Note	The baseline section number includes both an "offset" (e.g., "10" in the example above), as well as a possible "depth" (e.g., "8.2.8" in the BICEPS Content file example above.

How this baseline section offset and depth information is achieved inside the specification using various AsciiDoc constructs + preprocessing automation, is outside the scope of this article (see the referenced SDPi Content in AsciiDoc article); however, whatever that base "starting point" section number is for the file, it should be reflected in the name.

But what if it changes? Won’t that force renaming of all the files?! Of course, but since that is managed centrally at the domain TF level vs. the individual supplement and profile levels, this should rarely, if ever, happen.

Finally, note that due to limitations in AsciiDoc (as well as markdown and HTML5), though the file name may indicate a specific section numbering base, the internal content will not reflect that same numbering until it has been processed for conversion into, for example, HTML. In other words, though the content editor will include the necessary directives for a pre-publication processor pass, the real-time rendering will reflect normal section autonumbering. Deal with it …​

File Types and Examples

The following table provides a more detailed set of examples and considerations based on the various file "types" that will be included in the SDPi specification.

Table 1. SDPi File Types + Conventions & Examples

Type	Content	Name / Example	Considerations / Exceptions
Root SDPi Doc	Top-level file that is the starting point for integrating & processing all the other specification source files	sdpi-supplement.adoc	Singleton
Volume x (root)	Top-level "volume" document that integrates all the other subfile content for this section of the supplement.	tf1-main.adoc tf2-main.adoc tf3-main.adoc	Note that the root SDPi doc will incorporate these volume-specific documents, which in turn, will integrate the sub-file specification documents that are in that volume<x> folder.
Profiles	Volume 1 profile specifications	tf1-ch-2-overview.adoc tf1-ch-10-sdpi-p.adoc	Detailed profile specification; note that the profile overview content is in the "overview" file, along with other tf-1 / chapter 2 content.
Appendix	Appendices associated with a given volume	tf1-ch-c-use-cases.adoc tf2-ch-a-mdpws.adoc tf2-ch-b-gateway-V2.adoc	Note the lowercase appendix letter in the file name
Transactions	Specification content for each of the SDPi transactions	tf2-dev-23.adoc	One file per transaction; MPWS bindings and message exampls will be in the TF-2 Appendix A MDPWS file.
Content Modules	Volume 3 Semantic Content Specifications	tf3-ch-8.2.8-biceps-content.adoc tf3-ch-8.3.2-ventilator.adoc	SDC/BICEPS semantic content specifications; both genneral + specific to a device specialization; links from these files will be made to the respective BICEPS XML specification files in the /support-artifacts folder.
General Supplement Info	Content that is related to the supplement itself and will not be integrated into the final text TF.	sdpi-supplement-intro.adoc sdpi-supplement-issues.adoc	These files could be moved to a separate subfolder if they become too numerous.
General IHE Intro	Content that goes into the IHE TF-0 including actor descriptions, glossary entries, etc.	tf0-ch-9-copyrights.adoc tf0-ch-a-actors.adoc tf0-ch-b-transactions.adoc tf0-ch-d-glossary.adoc	Includes the IEEE copyright language; actor and transaction summary statements; any SDPi-specific terms to be added to the IHE Glossary; these files would go in a /volume0/ folder.
Images, PlantUML, Listings	Support graphic images and source + message listings that are incorporated directly into the AsciiDoc specifications	tf1-ch-10-sdpi-figure-actors.png tf1-ch-10-sdpi-figure-actors.puml tf2-ch-a-mdpws-listing-msg-probe-1.xml	These file names are aligned with the labeling that is associated with them in the supplement. Note: Figures and Tables are identified based on the section that they are included in, with dash numbers (-1, -2, -3) appended for multiple instances of the same type of element in the same section. Of course, this implies that you cannot include the same graphic in multiple places - which isn’t a bad thing.
Articles	Handy information for editors / content creators	sdpi-article-asciidoc-cheat-sheet.adoc sdpi-article-ihe-tf-asciidoc-cookbook.adoc	These two example articles will eventually be published on the wiki; however, given the need to be able to quickly refer to and edit them in a branch by every content editor, housing the articles here first is …​ handy!