[md2orchestra] What are the expected values of repository element attributes for name and version?

[kleihan]

How should the repository information in the markdown file be converted to Orchestra XML attributes? Here are some cases (please add more if needed) and proposed answers for discussion.

1. Level 1 header, e.g. # MyRepository missing completely ==> input file cannot be processed
2. # My Repository without version ==> name="My Repository" version="1.0"
3. # My Repository version without version number ==> name="My Repository" version="1.0"
4. # My Repository V2.0 ==> name="My Repository V2.0" version="1.0"
5. # My Repository Version 2.0 ==> name="My Repository" version="2.0"

[donmendelson]

Current code uses the entire heading to form the repository name; it does not look for a keyword.
The original prototype for Tablature had this case:

# Rules of Engagement 1.0

It does use the keyword "version" to locate the version token, which is redundant with name and inconsistent with the prototype.

[kleihan]

I edited the issue description. The keyword "Repository" is not required, only a level 1 header. This is also the reason why there can only be one level 1 header in a Tablature markdown file with the current software version.

Running Tablature v1.0.1 shows the following actual behavior for the cases in the issue description:

1. Level 1 header, e.g. # MyRepository missing completely ==> input file is processed, name and version not provided
2. # My Repository without version ==> name="My Repository" version="1.0"
3. # My Repository version without version number ==> name="My Repository version" version="1.0"
4. # My Repository V2.0 ==> name="My Repository V2.0" version="1.0"
5. # My Repository Version 2.0 ==> name="My Repository Version 2.0" version="2.0"

Case 1: unexpected result, to be seen as a convenience. Behavior must change if Tablature is to support multiple level 1 headings (allows to have repository and verbose text in a single markdown file representing an entire Rules of Engagement spec).

Cases 3-5: result consistent with @donmendelson's statement on current code but unexpected compared to issue description above. Open: should version information be repeated as part of the name or should the name end as soon as the keyword "version" is encountered?

Case 4: result as expected, Tablature requires keyword "version" (case-insensitive) to recognize a version number.

[donmendelson]

Suggested md2orchestra algorithm: The processor can look for keywords "repository" and "version".
If "repository" is present, use the next token as repository name.
if "repository" is not present, use the first token as name.
If "version" is present, use the next token as repository version.
If "version" is not present, examine the last token. If it is numeric, use it as a version number.
Otherwise, set version to default 1.0.

(With md-grammar issue FIXTradingCommunity/md-grammar#9, tokens will be allowed to have an internal space when surrounded by quotes, so a name with a space would be supported.)

[kleihan]

if "repository" is not present, use the first token as name.

@donmendelson in light of wanting to support multiple level 1 headings, why not do the following?

if "repository" is not present, skip content of source file until the next level 1 heading is encountered.

That would require # Repository ... to be used while at the same time would allow other level 1 headings, e.g. # Introduction.

[donmendelson]

@kleihan then orchestra2md should always output "repository" token before name.

[kleihan]

Yes, that would be the consequence. But if that is all there is to it then it seems like a low hanging fruit (if we make changes anyway) to achieve the goal of being able to put an entire Rules of Engagement spec into a single markdown file.

[donmendelson]

Metadata "title" should also be populated from the repository heading.

[donmendelson]

@kleihan If there are other sections at heading level 1 that are not imported into Orchestra, then they would be lost in a round trip. In my view, it would be better to keep "Introduction" at level 2 and import it as documentation about the repository. The Orchestra file would be self-contained.

[JThoennes]

@donmendelson @kleihan Just my 2 cents:

• I would prefer to always mandate the "version" keywords in lower case letters so cases 4 and 5 would not work.
• The default version if no version is provided could also be 0.1 to indicate a missing, pre-liminary version.

What is the recommended way to take part in this discussion? Via GitHub issues?