New module: AsciiDoc for Fedora Documentation Writers (part of #8)

This is a first attempt at giving Fedora Documentation Writers a one-
stop location to get started writing AsciiDoc. Instead of trying to
rewrite existing documentation about AsciiDoc, I linked out to helpful
resources maintained by the `asciidoctor.org` upstream.

However, this commit does write new documentation about handy snippets
to reuse in a Fedora-specific context. I also wrote a short guide on how
to use reusable attributes, since I realize this is something I have
done in many repositories I set up but never documented.

Part of #8 to improve the new contributor experience to Fedora
Documentation with AsciiDoc and Antora.

Signed-off-by: Justin W. Flory <git@jwf.io>

antora.yml

@@ -3,7 +3,7 @@
 name: fedora-docs
 
 # Title will be visible on the page.
-title: Fedora Docs
+title: Fedora Docs Team
 
 # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.
 version: master
@@ -15,3 +15,4 @@ start_page: ROOT:index
 nav:
 - modules/ROOT/nav.adoc
 - modules/contributing/nav.adoc
+- modules/asciidoc-fedora/nav.adoc

modules/asciidoc-fedora/nav.adoc

@@ -0,0 +1,3 @@
+* xref:index.adoc[AsciiDoc for Fedora]
+** xref:markup.adoc[Markup]
+** xref:reusable-attributes.adoc[Reusable attributes]

modules/asciidoc-fedora/pages/index.adoc

@@ -0,0 +1,7 @@
+= AsciiDoc for Fedora Documentation Writers
+
+This documentation section provides advice, tips, and resources for the Fedora Community writing AsciiDoc for Fedora documentation.
+The purpose of this section is not to duplicate what already exists, but to point you the right way.
+The idea is for you to spend less time remembering AsciiDoc or Antora nitpicks, and more time writing good docs!
+
+_Use the navigation bar in the side to navigate this section._

modules/asciidoc-fedora/pages/markup.adoc

@@ -0,0 +1,85 @@
+= AsciiDoc markup
+Fedora Documentation Team <docs@lists.fedoraproject.org>
+v0.0.1, 2020-08-26
+:toc:
+
+This page shares general information about writing in AsciiDoc as well as Fedora/Antora-specific syntax that comes up often in Fedora Documentation.
+
+
+[[basics]]
+== AsciiDoc basics
+
+[quote,asciidoctor.org]
+____
+AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text.
+____
+
+https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[*AsciiDoc Syntax Quick Reference*]::
+Handy cheat sheet of what the AsciiDoc markup looks like.
+Use this for quick references and checking up on how to formatting, lists, media content (images and video), table of contents, and more.
+
+https://asciidoctor.org/docs/asciidoc-recommended-practices/[*AsciiDoc Recommended Practices*]::
+Best practices about writing in AsciiDoc.
+Most importantly, note that https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[every sentence should be on its own line].
+
+
+[[snippets]]
+== Fedora Documentation snippets
+
+When you write Fedora Documentation, some things come up frequently.
+They may not be documented in general AsciiDoc documentation, like on `asciidoctor.org`.
+This section contains handy references for Fedora Documentation writers to copy and paste in their own AsciiDoc documents.
+
+[[internal-link]]
+=== Link to a page in the same repository
+
+Use the local path from the directory root to the AsciiDoc file name.
+
+.Example 1
+[source,adoc]
+----
+xref:page-name.adoc
+----
+
+.Example 2
+[source,adoc]
+----
+xref:packaging/policy/rules.adoc
+----
+
+[[module-link]]
+=== Link to a page in the same repository, but different module
+
+Like an internal link, but use a colon (`:`) to separate the module name.
+If you are not sure if you need this, you likely don't!
+Multiple modules bundled in the same repository is not currently a common scenario in Fedora Documentation.
+
+.Example 1
+[source,adoc]
+----
+xref:module::page-name.adoc
+----
+
+.Example 2
+[source,adoc]
+----
+xref:council:policy/guiding-policy.adoc
+----
+
+[[external-antora-link]]
+=== Link to a page in a different Fedora Documentation repository
+
+Link to another Fedora Documentation page that exists in another repository.
+Note that you *must* use the `name` field specified in the `antora.yml` file in the other repository or it will not work.
+
+.Example 1
+[source,adoc]
+----
+xref:name:module:page-name.adoc
+----
+
+.Example 2
+[source,adoc]
+----
+xref:council::code-of-conduct.adoc
+----

modules/asciidoc-fedora/pages/reusable-attributes.adoc

@@ -0,0 +1,88 @@
+= Reusable attributes
+Fedora Documentation Team <docs@lists.fedoraproject.org>
+v0.0.1, 2020-08-26
+:toc:
+
+This page explains how to use reusable metadata, or attributes, across multiple AsciiDoc documents in Fedora Documentation.
+
+
+[[why]]
+== Why reusable attributes?
+
+Sometimes you may want to use the same data across many AsciiDoc documents.
+Some examples are below:
+
+* Version releases (e.g. Fedora `N`)
+* URL prefixes or suffixes (e.g. `https://pagure.io/fesco/issue/`)
+* Dates and time (e.g. current year, like `2020`)
+
+For these and more use cases, *attributes* allow you to define some metadata in a single place, and reuse it in multiple places.
+
+
+== Overview
+
+There are two requirements for your Fedora Documentation project to use attributes.
+
+. Import attributes in your AsciiDoc file
+. Create an attributes file
+
+
+[[attributes-file]]
+== Create attributes file
+
+First, initialize an attributes file for a specific module, as shown below:
+
+[source,sh]
+----
+.
+└── ROOT
+    ├── nav.adoc
+    └── pages
+        ├── index.adoc
+        └── _partials
+            └── attributes.adoc
+----
+
+This is an example `attributes.adoc` from the xref:diversity-inclusion::index.adoc[Fedora Diversity & Inclusion Team]:
+
+[source,adoc]
+----
+:COMMBLOG: https://communityblog.fedoraproject.org
+:FISCALYEAR: FY20
+:FWIKI: https://fedoraproject.org/wiki
+:YEAR: 2020
+:MAILINGLIST: https://lists.fedoraproject.org/archives/list/diversity@lists.fedoraproject.org/
+:MAJOROSVER: 32
+----
+
+
+[[import]]
+== Import attributes
+
+Next, import the attributes file into your AsciiDoc document.
+Placing this macro on the top line will do the rest:
+
+[source,adoc]
+----
+\include::{partialsdir}/attributes.adoc[]
+----
+
+
+[[use-attributes]]
+== Use attributes in documentation
+
+After creating an attributes file *AND* import attributes, reference the attributes in AsciiDoc documents with the following syntax:
+
+[source,adoc]
+----
+{ATTRIBUTE}
+----
+
+See this example from the Fedora Diversity & Inclusion Team:
+
+[source,adoc]
+----
+*Full consensus* is required to approve new processes, make changes to
+existing team policies, and tickets requiring
+https://budget.fedoraproject.org/budget/{FISCALYEAR}/d-i.html[D&I budget].
+----

modules/contributing/nav.adoc

@@ -5,7 +5,6 @@
 *** xref:contributing-to-existing-docs.adoc[Contributing to Existing Documentation]
 *** xref:adding-new-docs.adoc[Adding New Documentation to the Site]
 *** xref:local-preview.adoc[Building a Local Preview]
-//** xref:markup.adoc[ASCIIDoc Markup]
 *** xref:git.adoc[Git for docs writers]
 //** xref:working-with-translations.adoc[Working with Translations]
 ** For designers: