Commit 2d46d7ca authored by Sarah White's avatar Sarah White Committed by Guillaume Grossetie
Browse files

edit each section to match focus of its heading

parent ad8d4868
......@@ -9,7 +9,7 @@ AsciiDoc is used to write notes, articles, documentation, books, web pages, slid
AsciiDoc is a plain text markup language for writing technical content.
It's packed with semantic elements and equipped with features to modularize and reuse content.
AsciiDoc content can be composed using a text editor, managed in a version control system, and published in a variety of output formats.
AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.
xref:#try[Get started,role=button]
https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Quick Reference,button,role="button invert"]
......@@ -30,13 +30,11 @@ image::./assets/img/intellij-asciidoc-editor.png[]
//* image:./assets/img/fedora-logo-white.svg[]
[#about,separator=.]
== Write once, publish anywhere. Write READMEs, books, or anything in between
== One language, many output formats. Publish READMEs, books, and everything in between
AsciiDoc provides all the semantic elements you need to write and publish a technical book.
And yet, it's simple enough to use for a README or note taking.
Where you'll find AsciiDoc used most often is for writing technical documentation.
It can also be used to create HTML-based slides for presentations.
Explore some of these use cases in this section.
AsciiDoc provides all the semantic elements you need to write and publish technical books.
You'll also find that AsciiDoc is an ideal fit for documentation.
And yet, it's simple enough to use for READMEs or taking notes.
[.tab]
--
......@@ -87,14 +85,15 @@ image::./assets/img/man-page-git-for-each-ref.png[]
--
[#try-it-out.try]
== Try it out: Experience the magic of a lightweight markup language
== Try AsciiDoc now: Experience the magic of a lightweight markup language
You write AsciiDoc using plain text.
That means most of what you type is what you want to communicate.
You only have to enter special characters (aka markup) when you need to encode meaning that cannot otherwise be inferred.
Start a line with a series of equal signs to make a section title.
Prefix text with an asterisk to make an item in a list.
[.attn]#Try it out below to see for yourself!#
You only enter markup characters when you need to encode meaning that can't be inferred.
[.attn]#Try writing with AsciiDoc in the editor below to see for yourself!#
// The next two lines should be used as hints in the content already in the interactive editor
//Start a line with a series of equal signs to make a section title.
//Prefix text with an asterisk to make an item in a list.
[#editor-code,asciidoc]
------
......@@ -115,10 +114,10 @@ puts 'Hello, World!'
------
[#compare.compare]
== How AsciiDoc stacks up: Compare AsciiDoc against alternative document formats
== How AsciiDoc stacks up: Compare AsciiDoc to other markup languages
AsciiDoc is designed to strike a balance between a formalized, machine-oriented syntax and plain text with shorthands.
In fact, it's able to capture and encode nearly all of the semantics of a formalized language while still being readable in source form.
AsciiDoc is designed to strike a balance between systematic, machine-oriented syntax and plain text with minimalist markup.
In fact, AsciiDoc can capture and encode nearly all of the semantics of a structured language while still being readable in source form.
Want to see how AsciiDoc stacks up against alternatives?
Browse the sample documents below to compare.
......@@ -221,7 +220,7 @@ include::{includedir}/dita-sample.adoc[]
AsciiDoc fits the same architectural goals into an **XML-free** package and is **widely supported**.
Documents can be partitioned into **units of content** and reused with the include directive.
Document references are defined **source-to-source** and translated into links between published files.
And syntax extensions invite **new markup and integrations** while keeping the language consistent.
Syntax extensions invite **new markup and integrations** while keeping the language consistent.
--
[.tab.compare]
......@@ -246,7 +245,7 @@ However, its reliance on **indentation**, non-traditional notation, and **syntax
include::{includedir}/rst-sample.adoc[]
------
AsciiDoc also aims to provide an **easy-to-read**, what-you-see-is-what-you-get syntax.
AsciiDoc 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.
......@@ -283,23 +282,21 @@ AsciiDoc processors bundle a **stylesheet** that requires **no web development**
[#specifications]
== Specification process: Governed by a language specification, always evolving
Although you'll likely interact with AsciiDoc through one of the language processors or an editor with AsciiDoc support, AsciiDoc is just the writing language.
The specification for that language is managed and governed by the AsciiDoc Language project and, at a higher level, by the AsciiDoc Working Group at the Eclipse Foundation.
Having a specification allows the language to be processed consistently by a variety of implementations that span language runtimes, authoring environments, and application integrations.
The process for developing the specification is underway.
The AsciiDoc Language specification will ensure AsciiDoc is processed consistently by implementations that span language runtimes, authoring environments, and application integrations.
The specification is managed and governed by the AsciiDoc Language project and, at a higher level, by the AsciiDoc Working Group at the Eclipse Foundation.
Development of the specification is currently underway.
https://asciidoc-wg.eclipse.org[Get involved,role=action]
[#tools]
== A growing ecosystem: Support for AsciiDoc is at your fingertips
== A growing ecosystem: Support for AsciiDoc
[.card]
--
[discrete]
=== Author
If you want to preview AsciiDoc, then you'll be interested in the browser and IDE plugins that provide tooling like a live preview.
Write and preview AsciiDoc content in your favorite text editor, IDE, or browser.
https://docs.asciidoctor.org[Explore,role=action]
--
......@@ -309,7 +306,7 @@ https://docs.asciidoctor.org[Explore,role=action]
[discrete]
=== Convert
If you want to convert AsciiDoc documents yourself, you may look for a processor like Asciidoctor.
Convert your AsciiDoc documents to HTML, DocBook, PDF, and more with an AsciiDoc processor.
https://docs.asciidoctor.org[Explore,role=action]
--
......@@ -319,7 +316,7 @@ https://docs.asciidoctor.org[Explore,role=action]
[discrete]
=== Publish
If you want your AsciiDoc content to be discovered, converted, and published into a website, then you'll want a static site generator or build tool that knows how to process AsciiDoc such as Antora, the Gradle or Maven plugin, Hugo, or Jekyll.
Publish your content using static site generators and build tools that know how to process AsciiDoc.
https://docs.asciidoctor.org[Explore,role=action]
--
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment