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