Skip to content

Latest commit

 

History

History
409 lines (278 loc) · 16.7 KB

sdpi-article-ihe-tf-asciidoc-cookbook.adoc

File metadata and controls

409 lines (278 loc) · 16.7 KB
Raw

IHE TF AsciiDoc Cookbook

Contents
Warning
 This is a straw-man article. Content hackers welcomed! Add content requests to section <<Topics Parking Lot>> below.

1. Cookbook Overview

This article provides a handy reference place for the conventions and templates that editors will apply in creating content for the SDPi specification. It is organized so as to help with specific editorial tasks (e.g., references, images, tables, metadata, etc.).

Related articles that support the information below include:

There are a few methods to review the HTML that will be rendered from the AsciiDoc sources:

  1. IntelliJ Editor has quick view panes that can be used during content development

  2. An "HTML" that can be used for creation of a .html version of the file (and included files) being edited

  3. GitHub Actions can be used to view the fully rendered document:

    1. Push the local branch to remote; this will automatically trigger "Verify and upload SDPi supplement" workflow action

    2. Use your browser to navigate to https://github.com/IHE/sdpi-fhir/actions[sdpi-fhir gihub actions page

    3. Select "All workflows" or the "Verify and …​" tab

    4. Note that it typically takes a minute or two to complete the workflow action — status will be displayed on the right side of your push’s row

    5. Select your branches latest upload (push remote)

    6. IF the action was successful, there will be listed in the "Artifacts" section; click on the artifact Name to download a ZIP of the rendered document.

    7. Extract the ZIP, select the "singlepage" subfolder and open the sdpi-supplement.html document

Enjoy AsciiDoc content creation!

2. Asciidoc Source Conventions

The following subsections specify conventions for the writing of Asciidoc markup. It makes use of [Backus-Naur forms](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form), which may include [Regular expressions](https://en.wikipedia.org/wiki/Regular_expression) (signified by enclosing slashes) to describe grammars for acceptable characters of symbols.

Note
 Following sections are in alphabetical order

2.1. Footnotes

See example from supplement introduction; note that this example puts the footnotes in the bottom of the table vs. page …​ matter?

2.2. Identifier naming

Asciidoc leverages identifiers for cross-referencing artifacts in Asciidoc markup. The following rule specifies is a general naming convention for identifiers that is used throughout this section:

Name ::= /^[a-z0-9_]+$/
Name

Custom name that contains small letters, digits and underscores only.

2.2.1. Identifier prefix

Identifiers shall be made up from the following rules:

Volume = 'vol0' | vol1' | 'vol2' | 'vol3'
ReferenceType ::= 'clause' | 'appendix' | 'listing' | 'figure' | 'table' | 'example' | 'ref'

BlockIdentifier ::= Volume '_' ReferenceType '_' Name
Volume

Target volume.

ReferenceType

The referenced block type.

Example 1. Example of including a clause name
[#vol2_clause_transactions]
== Transactions

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

2.2.2. Variables

Variables can be used to avoid repeating names or URIs in the Asciidoc source code. Variables shall be made up from the following rules:

VariableType ::= 'uri'

VariableName ::= 'var_' + [ VariableType + '_' ] + Name
VariableType

Type of the variable, currently URIs/URLs are to be specifically designated.

2.2.3. Definitions

Definition Names are just arbitrary character sequences according to the following rule:

DefinitionName ::= Name

2.2.4. Actors

Actor Names are definition names with a specific prefix:

ActorName ::= 'actor_' + Name

2.3. Image paths

Images are stored in the images sub-folder including any diagrams generated by the Asciidoc Diagram plugin.

2.4. Listing paths

Code listings are stored in the listings sub-folder.

2.5. Nested Tables

See example in supplement introduction #

2.6. Plant UML diagrams

PlantUML diagram sources are stored in the plantuml sub-folder.

  • A PlantUML diagram source shall be included by using the include directive (rather than inline)

  • A PlantUML diagram source shall contain skinparam dpi 300 for appropriate high-resolution rendering

  • If no custom color palette is applied on a PlantUML diagram, the PlantUML diagram’s source shall contain skinparam monochrome true for monochrome rendering

PlantUML diagram target names shall start with puml to easily identify any generated Plant UML artifacts in the images folder.

PlantUmlTarget = 'puml-' Name
Example of including a PlantUML diagram.

Note the leading puml- at the target option.

.Diagram title
[[vol2_figure_xyz]]
[plantuml, target=puml-vol2-figure-xyz, format=svg, reftext='{figure-caption} {counter:refnum}']
....
link:../plantuml/vol2-figure-xyz.puml[role=include]
....

2.7. SVG Graphics — PowerPoint to SVG + InkScape

For those graphics that are not PlantUML based, the preferred format is Scalable Vector Graphics (SVG) format. Since many of content developers utilize Microsoft PowerPoint as their graphics editor of choice, getting from a PowerPoint slide to an SVG file that renders well in AsciiDoc is a bit of a journey. The following tools and process — though a bit laborious — works well and reliably.

2.7.1. InkScape SVG Editing Tool

Before you begin, install the InkScape SVG editing tool. This open source tool is available for free download at: https://inkscape.org/release/1.1.2/platforms/ [inkscape.org/release/1.1.2/platforms].

  • Note: Version 1.1.2 should be downloaded at this point due to some feature changes in more recent versions. This should be rectified in the Q1 2023 update.

When installing, accept the normal "default" configuration options. Our use of the tool is very basic!

2.7.2. PowerPoint to SVG

The first part of the process is to convert a PowerPoint graphic to SVG format:

  1. PowerPoint file should have a single slide with the graphics to be converted. File should be named according to the file naming conventions (See sdpi-fhir wiki article SDPi File Organization Scheme — File Naming Conventions).

  2. During development & conversion, maintain the files (.pptx & .svg) in a separate local directory. Ultimately, they will be moved to the appropriate directories in the github repository (per the above article’s conventions)

  3. For the power point slide:

    • Select All objects (e.g., ctrl^a) to make sure only the objects in your graphic are included - delete any other objects on the slide (e.g., transparent boxes that don’t render).

    • Hide any background graphics: Design → Format Background → select Hide background graphics

  4. Convert to SVG: File → Save As → Scalable Vector Graphics Format (*.svg)

    • Note: Though there is only one slide per file, select "Just This One" when prompted for "Which slides do you want to export?"

Now you should have an SVG version of the graphic; hopefully in the same directory as the source .pptx file.

2.7.3. SVG to Final Cropped Version using InkScape

When PowerPoint exprts to SVG, it also includes the background area, which will display as a small graphic on a large white background. To crop the SVG to the final version that will be rendered in the AsciiDoc file, follow the following steps:

  1. Load the .svg file into InkScape (see above for installing the tool)

  2. Delete the background layer: double click anywhere on the background whitespace, press Del key.

  3. Crop the borders to 15 pixels around the graphic:

    • File → Document Properties → Page → Resize page to content …​

    • Set Top / Bottom / Left / Right to 15.0

    • Click "Resize page to drawing or selection"

    • There should now be a box around the graphic with a 15 pixel border

  4. Add a "background box" behind the graphic:

    • From the menu on the left of the tool’s window, select the red rectangle ("Create Rectangles and Squares")

    • Draw a box on top of the cropped graphic

    • Change the box to white (click white on the color strip at the bottom of the tool’s window)

    • Move the box to behind the graphic: Object → Lower to Bottom

  5. Save edited SVG file (to your working directory)

2.7.4. Move SVG Graphic Files to Repository

The final step is to move both the source (pptx) and final SVG files from your working folder to the designated folders in the sdpi-fhir repository:

  • SVG to SDPi_Supplement/asciidoc/images

  • PPTX to SDPi_Supplement/sources

Check the AsciiDoc source where the graphic is included to ensure that it is properly formatted.

2.8. PNG & JPG & Other Automatic Image Formats

In general, AsciiDoc automatically handles other image formats based on the file name extension (e.g., myGraphic.png).

  1. Note: The following path to the AsciiDoc images folder is due to the fact that this document is in the SDPi_Supplement articles folder. 

image::../asciidoc/images/ihe-logo.png[]

Which should render as:

Warning
 WHY DOESN’T THIS RENDER CORRECTLY EITHER HERE OR ON THE SUPPLEMENT’S TITLE PAGE?!

  1. ihe logo

  1. Note: Two colons "::" are needed if the graphic is on a line by itself; if it is in-line with other text, then a single colon ":" should be used.

Additional information is provided on the AsciiDoc Specify Image Format page. For general file types and formats information, consult the Mozilla Image File Type and Format Guide.

2.9. Section Numbering Challenges

IHE technical framework supplement documents are intended to be integrated into the main IHE DEV Technical Framework document. This means that section numbering in the supplement is discontiguous and is based on where it will ultimately be inserted. AsciiDoc of course does not support discontiguous section numbering and as a result, the content has to be annotated with directions for a post processor (i.e., asciidoc-converter tool) to render the proper section numbering in the HTML output.

2.9.1. Setting the Section Offset and Level

add content here#

2.9.2. Appendix Letters

add content here

2.10. Superscript / Subscript

Bring example from supplement overview using …​ and …​ respectively

2.11. Text Box for Editor’s Instructions

Many of the IHE Technical Framework Supplement sections include instructions for the editor who will ultimately migrate the supplemenbt content into the main (final text) Technical Framework specification. These instructions are typically contained in a text box at the start of a section.

For AsciiDoc, this text box is realized by defining a one-cell table, as follows:

[%noheader]
[%autowidth]
[cols="1"]
|===
|Add the following _*new or modified*_ actors to the IHE Technical Frameworks General Introduction Appendix A
|===

This would result in the following text:

Add the following *new or modified* actors to the IHE Technical Frameworks General Introduction Appendix A

2.12. Term & Acronym Definitions and References

Specialized terms and acronyms should be added to the TF-0 Glossary table and referenced appropriately throughout the specification text. For example, the special term "Participant Key Purposes" and acronmy "PKP" would be added to the glossary table as follows:

| [[term_participant_key_purposes,Participant Key Purposes (PKP)]] Participant Key Purposes
| These generally refer to the ISO/IEEE 11073-1070x standards that provide a consensus set of risk control measures aligned with the four core <<acronym_mdi>> functions:  <<term_plug_and_trust>>, reporting, alerting & external control.
|
| [[acronym_pkp,PKP]] PKP

Subsequent references in the AsciiDoc specification should utilize "term_" and "acronym_". If the acronym is only used locally, with in a single section or subsection, then it should be defined there at the outer most level and not formalized in the IHE Glossary.

Note
 The IHE TF-0 Appendix D glossary collects specialized (defined) terms used throughout all the IHE domain technical framework specifications. Any conflicts with other defined terms and acronyms may result in updating to the specifications.

2.13. Paragraphs - LONG Paragraph Conventions

Paragraphs with multiple sentences — which may be deemed "long" by some editors and readers! — should separate each sentence with a single new-line. This will make the AsciiDoc source much more readable without resulting in any format changes when rendered. For example:

First paragraph - first sentence.
Second sentence.
Third sentence.

Second paragraph ...

Would be rendered as:

  1. First paragraph - first sentence. Second sentence. Third sentence.

  2. Second paragraph …​

3. IHE Style Guide Conventions

IHE technical framework specifications follow a set of style conventions and associated templates. Though this is to some degree in "flux" given the movement to HTML-based specifications, the style conventions in the subsections below help ensure consistency in the IHE DEV SDPi content.

3.1. Table and Figure Numbering

TODO: section-based sequential table numbering + referencing w/ AsciiDoc examples

3.2. Bullet List Conventions

TODO: Review that the following is agreeable by the SDPi Editors

For a bulleted list of items, the final "full stop" character of each non-final bullet should be ";" semicolon, with the final bullet ending in a "." period. For example:

  1. First bullet;

  2. Second bullet;

  3. Final Bullet.

4. Topics Parking Lot

Include:

Add: Continuous Build process documentation …​ for multi-file / multi-page AsciiDoc sources * Section Numbering & Naming Conventions Much of this is specified in the IHE template, but see "depth" and discontinuous section numbering issues

Capture: indicate section depth + offset using something like …​

[#the_id,sdpi_num_offset=10] and

[#the_id,sdpi_num_level=+1] depth indicator

Also factor in Figure and Table numbering: section number + "-1" | "-2" …​

  • Non-section Number Based / cross-doc References

  • IHE TF UML Model

Include something that shows the interrelationships between blocks of content.

Important
 TBD - Need to determine how to formalize these kinds of UML models; drawn in "Magicdraw", to PNG, to XMl rep of some sort (collapsable inclusion?), used for this doc + for SST database extraction / processing

  • Mapping from UML to AsciiDoc Block Content

    • All special blocks should include a UML model for their content and be represented in the general TF UML model

    • Classes represent blocks (including referenced classes)

    • Class data elements represent block content

    • Contained classes represent nested block content that can have cardinality

    • …​

  • Reference Conventions (basic syntax, conventions)

  • Block basics

  • Block naming conventions

  • Block types

    • IHE TF Elements (with URI identifiers) - see UML Models

      • Profile + Profile Option

      • Actor + Actor Option + TF-0 Summary

      • Transaction (TF-0 summary + TF-2 detail)

      • Issues / Open & Closed (w/ ToI links & github Issue links)

      • TF-0 Glossary - Term of Art

      • BICEPS specification (e.g., XML for a specialization OR for a )

      • …​

    • RI "link" blocks (note: separate article proposed …​ needed?)

    • Requirement blocks

    • SES blocks + subsections

    • Use Case (Gherkin structured + General Appx. C & profile specific) - see UML model

Note
 Include UML model for each block type (per above)
Note
 For quick links and examples for AsciiDoc constructs that are used in the SDPi Supplement, see the wiki article: SDPi Editors' AsciiDoc Cheat Sheet