Skip to content

Crafting AsciiDoc based SDPi Supplement Content

Jump to bottom
Todd "AFC!" Cooper edited this page Apr 14, 2023 · 4 revisions

Crafting AsciiDoc-based SDPi Supplement Content

NOTE: THIS PAGE IS STILL UNDER DEVELOPMENT!

Word, markdown, …​ AsciiDoc?

Or …​ Why AsciiDoc? And …​ What IS AsciiDoc anyway?!

Traditionally, IHE technical framework (TF) specifications have been document-based using Word. Recently, though, efforts have been made to align IHE specification content and publication with what is used for HL7 FHIR, namely markdown content that is published as HTML. For example, see the IHE ITI Technical Framework web pages on profiles.ihe.net. So the transition from Word to markdown for all future HL7 and IHE technical specifications is well under way!

In pushing for an SDPi 1.0 specification "document", the question for the Gemini SES+MDI group is whether to make the transition now from Word to markdown (especially given that the Word document is already over 200 pages, though most of that is outline and scoping content) OR stay with Word and transition at a later date?

Consider also one of the unique aspects of the Gemini SES+MDI program, namely the goal to realize specifications that fully support RI+MC+RR (Requirements Interoperability + Model Centric + Regulatory (submission) Ready). Though a detailed treatment of these is beyond this article, it has become clear that pursuing these three represents a new level of value for all stakeholders, especially product developers, and given the nature of the systems envisaged by SDPi - an ecosystem of plug-and-trust medical technology products - they can be seen as required enablers to establish the mutual confidence needed to realize genuine SES+MDI.

With that, a Word-based approach was going to use constructs such as styles + bookmarks + links/references to "hack" in support for RI. Any decision to migrate to markdown specifications would also require providing a mechanism to integrate RI and move toward MC (e.g., formal MBSE / UML support) content.

Given that some Gemini program participants have standardized on the use of AsciiDoc for all their company-internal documentation, that too was placed on the table for consideration. Again, aligning the technologies and tooling used for standards specification with what is in general use in the companies advancing those standards, provides additional value and reduces inefficiencies.

Based on these three options - Word, markdown, AsciiDoc - the Gemini SDC+MDI group chose to go with AsciiDoc for the following reasons:

  1. Word is a short term “hack” at best …

    • IHE has already moved from Word to markdown & HTML publication

  2. Markdown was created for simple commenting and on-line content –

    • Publication in PDF and HTML works but support for RI+MC+RR … not so much

  3. AsciiDoc provides the best approach today for advancing to RI+MC+RR…

    • Strong built-in support for embedding metadata + defining type / object extensions

    • Can support model-based content now, better supporting integration into a single-source of truth specification database

    • Can support ALL the document-based artifacts created / consumed by the SDPi+FHIR program … including test-related assertions, scripts, and reports

    • Broad tooling support and platform integration + support community is equivalent to that of markdown

    • Content editors today will have to use either markdown or AsciiDoc or similar – pathway for integration of other sources (e.g., Word) to AsciiDoc is easily achieved

    • Support for Gherkin and other extensions already in place

Note: A more complete evaluation of the journey to AsciiDoc is captured in the presentation Gemini Publication Strategy (2022.07.22A)

With that, What IS AsciiDoc? (title of this section) and How do I get started? …​

Getting Started with AsciiDoc

As described on AciiDoc.org:

AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content. AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.

It should also be noted that AsciiDoc is NOT a markdown flavor – it is a language purpose-built for technical specifications, with an extensive support community and tooling integration. See the article "Compare AsciiDoc to other markup languages" on the AsciiDoc.org home page.

And of course, application/tool specific documentation …​

Toolchain: Authoring AsciiDoc-based Content

TODO: Capture (subsections) github support + IntelliJ / AsciiDoctor / PlantUML etc.

Support for creating and publishing AsciiDoc-based content is extensive, including native support in the GitHub editor (simply change from the default "md" to "AsciiDoc").

Authoring Using IntelliJ Platform

The primary tool chain that is being used for the SDPi Supplement development is the following:

  1. IntelliJ IDEA Platform

    • This integrated development environment provides a set of tools that allow for side-by-side panes for editing AsciiDoc content and real-time rendering view.

    • Download IntelliJ IDEA site provides two options:

      • Community Edition - Free, built on open source

      • Ultimate - 30 day free trial; annual license is $150 (as of 2022.08.01!)

      • For the purposes of SDPi content development, either should work, but compare the capabilities for your own needs

  2. IntelliJ AsciiDoctor Plugin

TODO: Sync with David G. on why node.js needed to be downloaded & installed + integration of GitHub CLI + setting PATH and other system environment variables + integration with GitHub from IntelliJ; Consider also a Visual Studio Code environment setup here

Other tools such as Antora may be utilized in the future.

Yes, there are some AsciiDoc WYSIWYG tools available …​ good luck …​ go for it!

Integrating Github Coordination

Once the basic platform is integrated, some github configuration is required in order to make a local clone of the DEV.SDPi repository, create a branch for your work, commit and push the local work to the remote (publicly accessible) repository and to generate pull requests. The following steps provide general github integration support, assuming the IntelliJ platform and / or Git Desktop or other is installed and being used:

  1. Github Account / Profile must be created; simply go to github.com and set up an account (free)

  2. Add your github ID to the DEV.SDPi repository collaboration team (send a request to Todd Cooper or David Gregorczyk).

  3. In IntelliJ, select the "Git::Manage Remotes…​" menu item and select "+" to open a local repository:

    1. URL for the main repo: https://github.com/IHE/DEV.SDPi

    2. URL for the repo wiki: https://github.com/IHE/DEV.SDPi.wiki.git

  4. Follow the directions for cloning a local copy of the repository, creating or opening a branch, etc.; first time configuration, will require you to authorize IntelliJ to access github as YOU! And other fun stuff …​

Note
 If you are using other "git" tools on the same computer (Git Desktop or even "git" from a terminal shell), when you log into "git" from one application, it is effective across all the applications. In other words, if a repository branch is selected in Github Desktop, then when you go to IntelliJ, that branch will be selected. If you modify a file in IntelliJ, then when you go to Git Desktop, the change information will be displayed. This is a very very good thing!!!

Workflow: From Creation to Review to Publication

Once the IntelliJ IDEA / AsciiDoctor Plugin installation is completed, the DEV.SDPi repo can be branched, fetched to the local drive, and opened (File→Open) for editing. The workflow for SDPi supplement updates can be summarized as follows:

  1. Branch the repo for the work to be done (using a browser interface, the desktop application, GitHub CLI, or other tooling)

  2. Push the branch and generate a Pull Request (back to the master)

  3. Review the changes on the regular SDPi Friday Zoom calls (or other meetings as necessary)

  4. Merge the approved changes

  5. <repeat ..>

Once a complete version is ready for review beyond the project team, an HTML version will be generated for review and approval within the IHE Devices domain. Github Pages may be used by the project team to automatically generate the publication-ready content.

Once the DEV domain approves the specification for broader review, it will be published on ihe.github.io/publications for public comment and finally published on profiles.ihe.net/DEV/. This workflow is further detailed in Authoring - Overall steps and Authoring - Detailed Publications committee process.

Toolchain: Word-based Content Crafting

TODO: Capture use of Pandoc for conversion from Word to AsciiDoc and then "hand" integration into repo

pandoc -r gfm --template=https://github.com/IHE/publications/wiki/ihe_template.html --metadata title="HIE-Whitepaper" --metadata path-prefix="../../" -w html -o index.html README.md

Toolchain: Repo Wiki Branching and Editing


NOTE (2022.08.01): The github notes below are based on a workable approach for controlled github wiki editing; this will be corrected and updated by wiser people in the near future!


Github Wiki Challenges & Tooling Approach

Though creating a branch in a github repo like DEV.SDPi is simple enough (from the "<> Code" tab), similar support for wiki update projects is not so obvious, though just as desirable when having multiple contributors author articles on the same wiki. To that end, after numerous documentation searches by a few individuals, the approach(es) below achieved the desired ends.

Of course, on the github wiki pages, if you have sufficient authorization, there is a green "New page" button toward the top right; however, this simply provides for limited authoring based on the github AsciiDoc (or markdown) editor, and there is no repo branching support provided for this authoring interface. Simple published page editing can also be accomplished using the built-in wiki page editor. Simply select the grey "Edit" button next to the "New page" button.

Example for a Github Wiki Branch Project

The following platform configuration was used for updating the DEV.SDPi github repo wiki:

  • Windows 10 on a Microsoft Surface 3 PC

  • Github Desktop (GHD)

  • PowerShell (PSGit) for GitHub CLI Command Line Interface (OR Terminal within InJ below)

  • IntelliJ (InJ) platform (for editing AsciiDoc content, see Toolchain: Authoring AsciiDoc-based Content)

Github wiki pages also provide a URL for cloning the wiki. See the "Clone this wiki locally" element on the right in the wiki page sidebar.

Based on the platform tools above, the following steps can be used to clone, branch, edit and publish DEV.SDPi repo wiki pages:

  1. Using PSGit, clone the wiki onto your local computer

  2. Create a new branch from the local wiki master

    • GHD: File "Add local repository …​" & follow the prompts providing the local file path to the wiki repo

    • GHD: Verify "Current repository" is set to DEV.SDPi.wiki

    • GHD: Under "Current branch" in the same status bar, select the down arrow, enter the name of the new branch & select "New branch" button

    • PSGit: git branch

      • The new branch should show up and be selected

      • "git branch -a" can be used to see what other branches may exist as well

  3. Make Branch Visible

    • PSGit: git push --set-upstream origin <branch name>

      • Now the branch will be visible to other developers

      • Note: using the command line may need a GitHub personal access token (PAT). Follow the detailed directions. Also, if the GHD application is being used and you are already logged in, a PAT will probably not be required. GitHub CLI also caches these, so as long as the PAT "lease" is active, you should not have to use it again.

  4. Edit wiki files

    • InJ: Edit the files in the local repository directory to your heart’s content!

    • GHD: As files are edited and saved to disk, the changes should also be reflected in the GHD windows

  5. Commit Branch w/ Message …​ as Normal

    • GHD: Commit the branch using GHD as normal for all github repos

  6. Publish Branch

    • GHD: Normally at this point, GHD would provide a way to "Create Pull Request" but for this local wiki …​ it is greyed out and not clear WHAT to do. So …​

    • PSGit: git branch

      • Confirm that the right branch is set

    • PSGit: git pull origin master

    • PSGit: git checkout master

    • PSGit: git merge <My Branch Name>

    • PSGit: git push -u origin master

      • Verify from the browser that the changes are now publicly published on the repo’s wiki

  7. Delete Branch (Optional)

    • Note: Normally this can be done from the github browser - but cannot switch to the DEV.SDPi.wiki project

    • PSGit: git branch -d <my branch name>

Note: Many people use different "git" tools or only the command line and never use the "desktop" tool. The general clone-branch-pull-merge-push-delete sequence above should be easily replicated with any git tooling.

AsciiDoc Editorial Guidelines

Detailed guidelines and conventions for integration of IHE Technical Framework content, especially the SDPi supplement, into AsciiDoc files is addressed in the wiki article:


Gemini SES+MDI Program

Gemini SES+MDI Program articles …​

Clone this wiki locally