From f887f1048b4c77ce82bb84c21592bbe46a3fbf5a Mon Sep 17 00:00:00 2001 From: Keith Hazelton Date: Mon, 15 May 2023 11:59:23 -0500 Subject: [PATCH] MBProMax --- docToolRec.adoc | 61 ++++++++++++++++++++++++++++------------ recoveredDocToolRec.adoc | 55 ++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 18 deletions(-) create mode 100644 recoveredDocToolRec.adoc diff --git a/docToolRec.adoc b/docToolRec.adoc index 73ce29f..ac94430 100644 --- a/docToolRec.adoc +++ b/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 + +|=== diff --git a/recoveredDocToolRec.adoc b/recoveredDocToolRec.adoc new file mode 100644 index 0000000..ac94430 --- /dev/null +++ b/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 + +|===