PSEC - Markdown Usage

Usage

Markdown is used extensively in the implementation of PSEC. There are 4 sources of the markdown text.

1. Markdown files with an .md extension and pointed at by file psec-root.md. All formatting codes used need to be supported including Customization strings.

2. The built in help system for CMDS is built using a stripped down markdown language. Specifically, Customization strings are not supported.

3. The help system used in the WorkFlow implementation uses markdown .md files to format the help files and the .psm1 files used to process each flow task. This is described in Workflow Directory Structure. Customization strings are not supported in the .md files but are in the .psm1 files.

4. Markdown text in .ps1 and .psm1 files used in the Site Build Process and identified with a <#.md marker. Customization strings are supported.

Site Build Process

This document site is built using documentation contained in multiple sources processed in the following sequence.

1. The source file psec-root.md.

2. Markdown source files .md pointed at by psec-root.md.

3. Markdown source text found in .ps1 and .psm1 files located in the PSEC execution library. The markdown text is extracted when the <#.md flag is detected. This is used to document classes and functions. The Task and TaskExec definitions are examples of such a design implementation of both classes and class methods.

4. Markdown source text found in .md, .ps1, and .psm1 pointed at by the PSEC_V4_FLOWS environment variable. In the latter 2 cases the markdown text is extracted when the <#.md flag is detected. This is used to document functions and classes and class methods. The .md file is the source for the specific task help or the specific workflow help.

Work files are stored in PSEC install location temp directory.

Text from the above files is formatted and merged into one file called merged-stream.md with Pandoc Utility safe boundary markers. It is stored in the temp directory.

The Pandoc Utility is called. The utility has a high startup cost and so the single invocation design minimises the startup cost. It produces merged-stream.html in the temp directory.

The merged-stream.html is split into the .html final output files.

Link reference markers may not exist until the final .html files are created. A special marker <span data-atat= ...> ... &lt/spab> is inserted to allow links to be created during the final split phase.

This is all orchestrated in the Generate Documentation Workflow.

Customization

The customization of standard markdown is minimal, mainly so that any standard editor markdown plugins can cope. They are:

1. Strings starting with @@ are examined and replaced with markdown according to the rules described in @@ String Replacement Rules described below.

2. The ### and === type headers can end with a {vbl} name. The document parser will create a marker in the document that the @@link.vbl will link to. The heading value will be used as the link text.

@@ String Replacement Rules

The format of the @@ string is @@verb.parm. If the verb is omitted then the default mode is assumed and rule 1 or 2 applies.

1. If the markdown belongs to a class, class method or class function, then the parm refers to a case-sensitive class name. Thus @@Task refers to the Task class.

2. If Rule 1 is not selected (mostly .md files) then parm refers to a entry in the Abbreviation Table described below. Thus @@Green-Check refers to the √ icon.

Otherwise the verb has the following valid meanings.

1. link The parm parameter will refer to a marker either defined in the Customization section or as the automatic creation of CMD verbs. Thus @@link.atat-rules refers to @@ String Replacement Rules and @@link.cmd-hh refers to @@;link.cmd-hh.

2. wpf A reference to a Windows Presentation Function will be created. Thus @@wpf.Form points to Form Object.

3. cls A reference to a PSEC class from .md code. Thus @@cls.Task points to Task.

4. hfunc A reference to a PSEC helper function from .md code. Thus @@hfunc.exists points to exists.

5. flow A reference to a PSEC flow .md description. Thus @@flow.demo-options-help points to Showcase Options.

To aid in the readabilty of links, *@@ strings may end with a . or , character (which is ignored). In the same vein, a suffix of .s will add an 's' to the link text. Thus @@wpf.Form.s will create Form Objects and @@cls.Task.s will create Tasks.

Invalid verbs will produce a red error marker in the final .html files and the error counted and logged in the build process status and log files.

Open HTML constructs

Although the Pandoc Utility does support embedded HTML, it is discouraged as it may cause unforeseen issues. The one exception to this rule is the use of the <a ...>...</a> tag which may be used to produce external pointing links. Thus <a href=https://pandoc.org/ target=_blank>I asked DebbiePointer to Pandoc Website</a> creates the link Pointer to Pandoc Website.

Abbreviation Table

The following table is defined in org.srp.psec.docs.GenPsecDocsEmitHtml and is used to insert abbreviations.

  HashMap<String,String> oSyms = new HashMap<>();
  {
    oSyms.put("Green-Check","<span class=\"icon-sym icon-green\">&#8730</span>");
    oSyms.put("Orange-Check","<span class=\"icon-sym icon-orange\">&#8730</span>");
    oSyms.put("Red-X","<span class=\"icon-sym icon-red\">X</span>");
    oSyms.put("Orange-X","<span class=\"icon-sym icon-orange\">X</span>");
    oSyms.put("Orange-Quest","<span class=\"icon-sym icon-orange\">?</span>");
    oSyms.put("Red-CfgErr","<span class=\"icon-sym icon-red\">&#9660</span>");
    oSyms.put("Prop-Bar","<span class=\"icon-sym\">&#x2261</span>");
  }