From 86189e0ba97fa92c8a86a4e9931beb4a0699da16 Mon Sep 17 00:00:00 2001 From: Dan Allen <dan@opendevise.com> Date: Tue, 1 Feb 2022 03:25:06 -0700 Subject: [PATCH] update verbiage for language comparisons and adjust styles to make it easier to read --- assets/css/main.css | 9 +++++++-- pages/index.adoc | 31 ++++++++++++------------------- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/assets/css/main.css b/assets/css/main.css index 066bf3b..264e9ef 100644 --- a/assets/css/main.css +++ b/assets/css/main.css @@ -418,8 +418,9 @@ section.compare .tabset .tab-pane h4 { } section.compare .tabset .paragraph { - color: rgb(17 24 39 / 85%); - padding: 0 0.75rem; + color: #272e3b; + padding-left: 0.5em; + padding-right: 0.5em; } section.compare .tabset > .content .title { @@ -674,6 +675,10 @@ section.docs a { font-size: 2.25rem; } +.main p { + line-height: 1.4; +} + .main a.button { font-size: 1.15rem; text-decoration: none; diff --git a/pages/index.adoc b/pages/index.adoc index c1a3704..068a6ae 100644 --- a/pages/index.adoc +++ b/pages/index.adoc @@ -112,10 +112,8 @@ include::{includedir}/sample.docbook[] ---- DocBook is an **XML schema** for writing books and manuals about technical subjects. -It has an extensive catalog of tags for denoting content structures and elements. -Although **well-supported by tools**, -writing in DocBook is tedious because the **content is overshadowed** by the markup, -there are **a lot of tags** to remember, and **XML indentation** can be a major distraction. +It boasts an extensive catalog of tags for denoting content structures and elements. +Although **well-supported** by tools, writing in DocBook is tedious because the **content is overshadowed** by the markup, there are **a lot of tags** to remember, and **XML indentation** can be a major distraction. [source,asciidoc,role=editor] ----- @@ -123,11 +121,8 @@ include::{includedir}/docbook.adoc[] ----- **Content is the central focus** in AsciiDoc. -The document starts off with **no ceremonial prologue**, -much of the structure is inferred from its **line-oriented** arrangement, -there's **no indentation** needed, and instead of XML tags, -content is marked up with **shorthand notations**. -And yet, you can still produce DocBook from AsciiDoc to tie into existing toolchains. +The document starts off with **no ceremonial prologue**, much of the structure is inferred from its **line-oriented** arrangement, **no indentation** is needed, and a handful of **shorthand notations** are used in place of XML tags to mark up content. +Best of all, you can still produce DocBook from AsciiDoc to tie into existing toolchains. -- [.tab.compare] @@ -194,22 +189,20 @@ And syntax extensions invite **new markup and integrations** while keeping the l include::{includedir}/sample.rst[] ---- -reStructuredText is a plaintext markup language designed for use in Python docstrings and other documentation domains. -Its intended purpose is for conversion to structured data formats and thus has an extensive and extensible syntax. -The language is line-oriented, making the content easy to see and the separation between block elements fairly evident. -Its reliance on indentation, non-traditional notation, and excessive syntax variations can make the document feel esoteric and hard to reason about. -While seasoned writers may understand the rules, newcomers can struggle to grasp the syntax. +reStructuredText is **plain text markup** for use in docstrings and formal documentation. +It offers an extensible syntax for producing structured output. +It's **line-oriented** design keeps the content clear and the separation of blocks evident. +However, its reliance on **indentation**, non-traditional notation, and **syntax variations** make the language **esoteric** and hard for newcomers to grasp. [source,asciidoc,role=editor] ----- include::{includedir}/rst.adoc[] ----- -Feature by feature, AsciiDoc is very comparable to reStructuredText. -Both focus on providing an easy-to-read, what-you-see-is-what-you-get plaintext syntax. -AsciiDoc arguably adheres closer to this goal by making indentation mostly insignificant, relying on block delimiters, and staying more true to conventional notation. -There are only a handful of patterns to remember in AsciiDoc, such as named blocks, macros, and formatting pairs, which are repeated throughout the language. -A newcomer should be able to pick up the syntax mostly by intuition alone. +AsciiDoc also aims to provide an **easy-to-read**, what-you-see-is-what-you-get syntax. +It attains this goal by making most **indentation insignificant**, using clear block boundaries, and relying on **conventional notation**. +AsciiDoc is composed of **a few patterns**, such as delimited blocks, macros, and formatting pairs. +A newcomer can pick up the syntax mostly by intuition alone. -- [.tab.compare] -- GitLab