From e0e42478aba41c5fa7abdbd897e85c97c89d4613 Mon Sep 17 00:00:00 2001
From: "Kyle J. McKay"
Date: Mon, 9 Jan 2017 23:56:44 -0800
Subject: [PATCH] {basics,syntax}.md: clean up formatting
Clean up the formatting in baiscs and syntax to make it
more readable as a text document.
This is now possible by making use of the automatic
anchors for top-level headers and '~~~~~' style h3's.
Signed-off-by: Kyle J. McKay
---
basics.md | 42 ++++++++------
syntax.md | 160 +++++++++++++++++++++++++++++++++++-------------------
2 files changed, 129 insertions(+), 73 deletions(-)
diff --git a/basics.md b/basics.md
index 9215305..7bfb4ed 100644
--- a/basics.md
+++ b/basics.md
@@ -1,13 +1,14 @@
+================
Markdown: Basics
================
-
+* _[Markdown Basics]( "Markdown Basics")_
+* [Syntax][]
+* [License][]
+- - - - -
+------------------------------------------------
Getting the Gist of Markdown's Formatting Syntax
------------------------------------------------
@@ -25,11 +26,14 @@ and translate it to XHTML.
**Note:** This document is itself written using Markdown; you
can [see the source for it by adding `.md` to the URL] [src].
- [s]: syntax.html "Markdown Syntax"
+ [syntax]: syntax.html "Markdown Syntax"
+ [license]: license.html "License Information"
[src]: basics.md
-## Paragraphs, Headers, Blockquotes ##
+--------------------------------
+Paragraphs, Headers, Blockquotes
+--------------------------------
A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like
@@ -102,8 +106,9 @@ Output:
-
-### Phrase Emphasis ###
+~~~~~~~~~~~~~~~
+Phrase Emphasis
+~~~~~~~~~~~~~~~
Markdown uses asterisks and underscores to indicate spans of emphasis.
@@ -126,8 +131,9 @@ Output:
Or, even, strike through instead.
-
-## Lists ##
+-----
+Lists
+-----
Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
`+`, and `-`) as list markers. These three markers are
@@ -191,8 +197,9 @@ Output:
-
-### Links ###
+~~~~~
+Links
+~~~~~
Markdown supports two styles for creating links: *inline* and
*reference*. With both styles, you use square brackets to delimit the
@@ -248,7 +255,9 @@ Output:
The New York Times.
-### Images ###
+~~~~~~
+Images
+~~~~~~
Image syntax is very much like link syntax.
@@ -267,8 +276,9 @@ Both of the above examples produce the same output:
-
-### Code ###
+~~~~
+Code
+~~~~
In a regular paragraph, you can create code span by wrapping text in
backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
diff --git a/syntax.md b/syntax.md
index d1fee7f..ba7978c 100644
--- a/syntax.md
+++ b/syntax.md
@@ -1,45 +1,50 @@
+================
Markdown: Syntax
================
-
-
-
-* [Overview](#overview)
- * [Philosophy](#philosophy)
- * [Inline HTML](#html)
- * [Automatic Escaping for Special Characters](#autoescape)
-* [Block Elements](#block)
- * [Paragraphs and Line Breaks](#p)
- * [Headers](#header)
- * [Blockquotes](#blockquote)
- * [Lists](#list)
- * [Code Blocks](#precode)
- * [Horizontal Rules](#hr)
-* [Span Elements](#span)
- * [Links](#link)
- * [Emphasis](#em)
- * [Code](#code)
- * [Images](#img)
-* [Miscellaneous](#misc)
- * [Backslash Escapes](#backslash)
- * [Automatic Links](#autolink)
+* [Markdown Basics][]
+* _[Syntax]( "Markdown Syntax Documentation")_
+* [License][]
+
+- - - - -
+
+* [Overview][]
+ * [Philosophy][]
+ * [Inline HTML][]
+ * [Automatic Escaping for Special Characters][]
+* [Block Elements][]
+ * [Paragraphs and Line Breaks][]
+ * [Headers][]
+ * [Blockquotes][]
+ * [Lists][]
+ * [Code Blocks][]
+ * [Horizontal Rules][]
+* [Span Elements][]
+ * [Links][]
+ * [Emphasis][]
+ * [Code][]
+ * [Images][]
+* [Miscellaneous][]
+ * [Backslash Escapes][]
+ * [Automatic Links][]
**Note:** This document is itself written using Markdown; you
can [see the source for it by adding `.md` to the URL][src].
- [b]: basics.html "Markdown Basics"
+ [markdown basics]: basics.html "Markdown Basics"
+ [license]: license.html "License Information"
[src]: syntax.md
- - - - -
-Overview
+--------
+Overview
+--------
-Philosophy
+~~~~~~~~~~
+Philosophy
+~~~~~~~~~~
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
@@ -66,8 +71,9 @@ blockquotes look like quoted passages of text, assuming you've ever
used email.
-
-Inline HTML
+~~~~~~~~~~~
+Inline HTML
+~~~~~~~~~~~
Markdown's syntax is intended for one purpose: to be used as a
format for *writing* for the web.
@@ -117,8 +123,9 @@ link or image syntax, go right ahead.
Unlike block-level HTML tags, Markdown syntax *is* processed within
span-level tags.
-
-Automatic Escaping for Special Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Automatic Escaping for Special Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In HTML, there are two characters that demand special treatment: `<`
and `&`. Left angle brackets are used to start tags; ampersands are
@@ -176,11 +183,13 @@ and `&` in your example code needs to be escaped.)
- - - - -
+--------------
+Block Elements
+--------------
-Block Elements
-
-
-Paragraphs and Line Breaks
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Paragraphs and Line Breaks
+~~~~~~~~~~~~~~~~~~~~~~~~~~
A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like a
@@ -206,8 +215,9 @@ work best -- and look better -- when you format them with hard breaks.
[l]: #list
-
-
+~~~~~~~
+Headers
+~~~~~~~
Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
@@ -261,7 +271,9 @@ determines the header level.) :
### This is an H3 ######
-Blockquotes
+~~~~~~~~~~~
+Blockquotes
+~~~~~~~~~~~
Markdown uses email-style `>` characters for blockquoting. If you're
familiar with quoting passages of text in an email message, then you
@@ -311,7 +323,9 @@ example, with BBEdit, you can make a selection and choose Increase
Quote Level from the Text menu.
-Lists
+~~~~~
+Lists
+~~~~~
Markdown supports ordered (numbered) and unordered (bulleted) lists.
@@ -468,8 +482,9 @@ line. To avoid this, you can backslash-escape the period:
1986\. What a great season.
-
-Code Blocks
+~~~~~~~~~~~
+Code Blocks
+~~~~~~~~~~~
Pre-formatted code blocks are used for writing about programming or
markup source code. Rather than forming normal paragraphs, the lines
@@ -556,8 +571,9 @@ asterisks are just literal asterisks within a code block. This means
it's also easy to use Markdown to write about Markdown's own syntax.
-
-Horizontal Rules
+~~~~~~~~~~~~~~~~
+Horizontal Rules
+~~~~~~~~~~~~~~~~
You can produce a horizontal rule tag (`
`) by placing three or
more hyphens, asterisks, or underscores on a line by themselves. If you
@@ -577,9 +593,14 @@ following lines will produce a horizontal rule:
- - - - -
-Span Elements
-Links
+-------------
+Span Elements
+-------------
+
+~~~~~
+Links
+~~~~~
Markdown supports two style of links: *inline* and *reference*.
@@ -693,7 +714,7 @@ using either the setext-style or atx-style automatically have an
anchor id and link definition added for them provided there is not
already a previous definition with the same id. You can use this
to place a table-of-contents at the top of the document that links
-to subsections later in the document.
+to subsections later in the document. Just like this document.
Here's an example of reference links in action:
@@ -742,7 +763,9 @@ you can add links without interrupting the narrative flow of your
prose.
-Emphasis
+~~~~~~~~
+Emphasis
+~~~~~~~~
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
emphasis. Text wrapped with one `*` or `_` will be wrapped with an
@@ -790,7 +813,9 @@ escape it:
\*this text is surrounded by literal asterisks\*
-Code
+~~~~
+Code
+~~~~
To indicate a span of code, wrap it with backtick quotes (`` ` ``).
Unlike a pre-formatted code block, a code span indicates code within a
@@ -845,7 +870,9 @@ to produce:
equivalent of —
.
-Images
+~~~~~~
+Images
+~~~~~~
Admittedly, it's fairly difficult to devise a "natural" syntax for
placing images into a plain text document format.
@@ -885,18 +912,36 @@ use regular HTML `` tags.
- - - - -
-Miscellaneous
+-------------
+Miscellaneous
+-------------
-Automatic Links
+~~~~~~~~~~~~~~~
+Automatic Links
+~~~~~~~~~~~~~~~
-Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
+Markdown supports a shortcut style for creating "automatic" links for URLs
+and email addresses: simply surround the URL or email address with angle
+brackets or don't. What this means is that if you want to show the actual text
+of a URL or email address, and also have it be a clickable link, you can do:
-Markdown will turn this into:
+or this:
+
+ http://example.com/
+
+Markdown will turn that into:
+
+ <http://example.com/>
+
+or this:
http://example.com/
+If Markdown is not quite grabbing the right link when it's not surrounded
+by angle brackets then just add the angle brackets to avoid the guessing.
+
Automatic links for email addresses work similarly, except that
Markdown will also perform a bit of randomized decimal and hex
entity-encoding to help obscure your address from address-harvesting
@@ -919,8 +964,9 @@ them. It's better than nothing, but an address published in this way
will probably eventually start receiving spam.)
-
-Backslash Escapes
+~~~~~~~~~~~~~~~~~
+Backslash Escapes
+~~~~~~~~~~~~~~~~~
Markdown allows you to use backslash escapes to generate literal
characters which would otherwise have special meaning in Markdown's