From af0119dc64075818c42d52a45d6100dfd26bf7d9 Mon Sep 17 00:00:00 2001 From: Justin W. Flory Date: Sep 02 2020 22:38:52 +0000 Subject: 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 --- diff --git a/antora.yml b/antora.yml index 8ad4468..1f74f1c 100644 --- a/antora.yml +++ b/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 diff --git a/modules/asciidoc-fedora/nav.adoc b/modules/asciidoc-fedora/nav.adoc new file mode 100644 index 0000000..2cc2195 --- /dev/null +++ b/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] diff --git a/modules/asciidoc-fedora/pages/index.adoc b/modules/asciidoc-fedora/pages/index.adoc new file mode 100644 index 0000000..4353d67 --- /dev/null +++ b/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._ diff --git a/modules/asciidoc-fedora/pages/markup.adoc b/modules/asciidoc-fedora/pages/markup.adoc new file mode 100644 index 0000000..234c3aa --- /dev/null +++ b/modules/asciidoc-fedora/pages/markup.adoc @@ -0,0 +1,85 @@ += AsciiDoc markup +Fedora Documentation Team +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 +---- diff --git a/modules/asciidoc-fedora/pages/reusable-attributes.adoc b/modules/asciidoc-fedora/pages/reusable-attributes.adoc new file mode 100644 index 0000000..0db25b5 --- /dev/null +++ b/modules/asciidoc-fedora/pages/reusable-attributes.adoc @@ -0,0 +1,88 @@ += Reusable attributes +Fedora Documentation Team +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]. +---- diff --git a/modules/contributing/nav.adoc b/modules/contributing/nav.adoc index ffd3157..be16175 100644 --- a/modules/contributing/nav.adoc +++ b/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: