MBProMax

docToolRec.adoc

@@ -2,29 +2,54 @@
 :hide-uri-scheme:
 
 - - -
-_2023-05-14 13:48:53 outline of documentation tool recommendation_
+_2023-05-14 13:48:53 Draft documentation tool option comparisons_
 
 ==== I. Deliverables
+
+. A documentation entry system with source files under version control
+. A process that creates a web accessible documentation site from the source repository
+. A CI/CD pipeline that triggers the publication process on a push to the source repository
+
 ==== II. Requirements
-==== III. Comparison of textual entry and editing tools: Markdown vs Asciidoc
 
-[cols=2*,stripes=odd]
-|===
-^| *MARKDOWN* ^| *ASCIIDOC*
-2+^|*Basic text entry, editing, and preview*
-|Cell in column 1, row 3
-|Cell in column 2, row 3
-2+^|*Feature syntax*
-| https://www.markdownguide.org/basic-syntax/
-| https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/
+What features of Confluence are used in our wiki content? Are there counterparts in the other options?
+
+==== III. Comparison of text entry and editing tools: Markdown vs Asciidoc
+
+[cols=3*,stripes=odd]
 |===
+^| *FEATURE/ASPECT* ^|*MARKDOWN* ^| *ASCIIDOC*
+
+|Basic text entry, editing, and preview
+|https://code.visualstudio.com/docs/languages/markdown[VS Code support for Markdown]
+|https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[Asciidoc support for VS Code]
 
-===== 2nd
+| Distinguishing features
+| Broad adoption, greater volume of published content, simple syntax for basic features, enhanced features available in various markdown flavors +
+| Complex tables, asides, definition lists, includes, sidebars, table of contents, live snippets from source code, anchors, in-file metadata, attribute/variable support, ifdef/ifndef for conditional inclusion 
 
-. List item
-.. Nested list item
-... Deeper nested list item
-. List item
- .. Another nested list item
-. List item
+| Flavors and Standards
+| Markdown (MD) plus varieties: Github Flavored Markdown (GFM), GitLab Flavored Markdown (GLFM, based on https://commonmark.org/[CommonMark])
+| Asciidoc specification is governed by the Asciidoc Working Group under Eclipse
 
+|Publication process
+|Markdown -> Jekyll -> GitHub Pages +
+Markdown -> Jekyll -> GitLab Pages +
+Output: HTML, pdf, more via Pandoc
+|Asciidoc -> https://antora.org/[Antora] -> GitLab Pages +
+Asciidoc -> Antora -> GitLab Pages +
+Output: HTML, pdf, Docbook, man pages, EPUB3, Reveal.js via Asciidoctor CLI +
+Multi-repository documentation sites via Antora
+
+|CI/CD support
+|Jekyll to GitHub Pages via Github Actions; To GitLab pages via https://docs.gitlab.com/ee/user/markdown.html[GitLab Flavored Markdown] (based on Kramdown) +
+|Antora to GitLab Pages via .gitlab-ci.yml playbook; to GitHub pages via Github Actions with .nojekyll directive
+
+|Conversion between markdown and asciidoc
+|https://github.com/asciidoctor/kramdown-asciidoc[markdown to asciidoc]
+|https://github.com/opendevise/downdoc[asciidoc to markdown]
+
+|
+|HTML, pdf, Docbook, man pages, EPUB3, Reveal.js via Asciidoctor CLI 
+
+|===

recoveredDocToolRec.adoc

@@ -0,0 +1,55 @@
+=== docToolRec.adoc
+:hide-uri-scheme:
+
+- - -
+_2023-05-14 13:48:53 Draft documentation tool option comparisons_
+
+==== I. Deliverables
+
+. A documentation entry system with source files under version control
+. A process that creates a web accessible documentation site from the source repository
+. A CI/CD pipeline that triggers the publication process on a push to the source repository
+
+==== II. Requirements
+
+What features of Confluence are used in our wiki content? Are there counterparts in the other options?
+
+==== III. Comparison of text entry and editing tools: Markdown vs Asciidoc
+
+[cols=3*,stripes=odd]
+|===
+^| *FEATURE/ASPECT* ^|*MARKDOWN* ^| *ASCIIDOC*
+
+|Basic text entry, editing, and preview
+|https://code.visualstudio.com/docs/languages/markdown[VS Code support for Markdown]
+|https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[Asciidoc support for VS Code]
+
+| Distinguishing features
+| Broad adoption, greater volume of published content, simple syntax for basic features, enhanced features available in various markdown flavors +
+| Complex tables, asides, definition lists, includes, sidebars, table of contents, live snippets from source code, anchors, in-file metadata, attribute/variable support, ifdef/ifndef for conditional inclusion 
+
+| Flavors and Standards
+| Markdown (MD) plus varieties: Github Flavored Markdown (GFM), GitLab Flavored Markdown (GLFM, based on https://commonmark.org/[CommonMark])
+| Asciidoc specification is governed by the Asciidoc Working Group under Eclipse
+
+|Publication process
+|Markdown -> Jekyll -> GitHub Pages +
+Markdown -> Jekyll -> GitLab Pages +
+Output: HTML, pdf, more via Pandoc
+|Asciidoc -> https://antora.org/[Antora] -> GitLab Pages +
+Asciidoc -> Antora -> GitLab Pages +
+Output: HTML, pdf, Docbook, man pages, EPUB3, Reveal.js via Asciidoctor CLI +
+Multi-repository documentation sites via Antora
+
+|CI/CD support
+|Jekyll to GitHub Pages via Github Actions; To GitLab pages via https://docs.gitlab.com/ee/user/markdown.html[GitLab Flavored Markdown] (based on Kramdown) +
+|Antora to GitLab Pages via .gitlab-ci.yml playbook; to GitHub pages via Github Actions with .nojekyll directive
+
+|Conversion between markdown and asciidoc
+|https://github.com/asciidoctor/kramdown-asciidoc[markdown to asciidoc]
+|https://github.com/opendevise/downdoc[asciidoc to markdown]
+
+|
+|HTML, pdf, Docbook, man pages, EPUB3, Reveal.js via Asciidoctor CLI 
+
+|===