From 0236f8a6bab7fb73b0f966937d950a326d33caa7 Mon Sep 17 00:00:00 2001 From: Brian (bex) Exelbierd Date: Jul 29 2018 12:50:02 +0000 Subject: antora conversion --- diff --git a/.gitignore b/.gitignore index 2333f31..9f3ebf5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,3 @@ -## AsciiBinder-specific ignores -_preview -_package -*.swp -diag-*.png -diag-*.png.cache - +build +cache +public diff --git a/Common_Content/Feedback.adoc b/Common_Content/Feedback.adoc deleted file mode 100644 index d11787f..0000000 --- a/Common_Content/Feedback.adoc +++ /dev/null @@ -1,26 +0,0 @@ - -:experimental: - -=== We want feedback -indexterm:[feedback,contact information for this manual] -If you find errors or have suggestions for improvement, we want your advice. Submit a report in Bugzilla against the product `{PRODUCT}` and the component `{BOOKID}`. The following link automatically loads this information for you: {BZURL}. - -In Bugzilla: - -. Provide a short summary of the error or your suggestion in the `Summary` field. - -. Copy the following template into the `Description` field and give us the details of the error or suggestion as specifically as you can. If possible, include some surrounding text so we know where the error occurs or the suggestion fits. -+ -[subs="quotes"] ----- -Document URL: - -Section number and name: - -Error or suggestion: - -Additional information: - ----- - -. Click the btn:[Submit Bug] button. diff --git a/Common_Content/Legal_Notice.adoc b/Common_Content/Legal_Notice.adoc deleted file mode 100644 index b65d4a5..0000000 --- a/Common_Content/Legal_Notice.adoc +++ /dev/null @@ -1,22 +0,0 @@ - -:experimental: - -Copyright {YEAR} {HOLDER}. - -The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at link:++http://creativecommons.org/licenses/by-sa/3.0/++[]. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. - -Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. - -Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. - -For guidelines on the permitted uses of the Fedora trademarks, refer to link:++https://fedoraproject.org/wiki/Legal:Trademark_guidelines++[]. - -*Linux* (R) is the registered trademark of Linus Torvalds in the United States and other countries. - -*Java* (R) is a registered trademark of Oracle and/or its affiliates. - -*XFS* (R) is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. - -*MySQL* (R) is a registered trademark of MySQL AB in the United States, the European Union and other countries. - -All other trademarks are the property of their respective owners. diff --git a/Common_Content/images/title_logo.svg b/Common_Content/images/title_logo.svg deleted file mode 100644 index e8fd52b..0000000 --- a/Common_Content/images/title_logo.svg +++ /dev/null @@ -1,61 +0,0 @@ - - - - - - - - - - - - - - - - - - - diff --git a/README.md b/README.md index c7a235d..6ef85d8 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,43 @@ # Fedora Documentation Guide -This is the content repository for the Fedora Documentation Guide +Please report Issues and submit Pull Requests for **Content Fixes** here. +Never done a pull request (or "PR")? Here's the [Pagure documentation for +Pull Requests](https://docs.pagure.org/pagure/usage/pull_requests.html). -Please report Issues and submit Pull Requests for **Content Fixes** here. General appearance issues and publishing issues should be reported against the [publisher](https://pagure.io/fedora-docs/docs-fp-o). -## How to edit this document +General appearance issues and publishing issues should be reported against +the [publishing software](https://pagure.io/fedora-docs/docs-fp-o). -This document is coded in AsciiDoc. The content is in the en-US directory. There is a shared entity file in the en-US directory. Do not edit the content in the Common_Content directory. +## How to edit these documents -## Testing your changes locally +All of this is written in AsciiDoc. It's a simple mostly-plain-text +markup language. You may want to look at: -To test your changes, first install `asciibinder` -$ gem install ascii_binder +* [AsciiDoc Syntax Quick Reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) +* [AsciiDoc Writer’s Guide](http://asciidoctor.org/docs/asciidoc-writers-guide/) +* [Antora Documentation](https://docs.antora.org/antora/1.0/page/) -To build your changes, from the root directory: + +## Local preview + +This repo includes scripts to build and preview the contents of this repository. + +**NOTE**: Please note that if you reference pages from other repositoreis, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions. + +Both scripts use docker, so please make sure you have it installed on your system. Please see below for instructions. + +To build and preview the site, run: + +``` +$ ./build.sh && ./preview.sh +``` + +The result will be available at http://localhost:8080 + +### Installing docker on Fedora ``` -$ asciibinder package -$ firefox _package/main/index.html +$ sudo dnf install docker +$ sudo systemctl start docker && sudo systemctl enable docker ``` diff --git a/_distro_map.yml b/_distro_map.yml deleted file mode 100644 index e55d33e..0000000 --- a/_distro_map.yml +++ /dev/null @@ -1,11 +0,0 @@ ---- -fedora: - name: Fedora Documentation Guide - author: Fedora Documentation Project - site: main - site_name: Home - site_url: https://docs.fedoraproject.org/ - branches: - master: - name: documentation-guide - dir: documentation-guide diff --git a/_images/404.html b/_images/404.html deleted file mode 100644 index f5963e8..0000000 --- a/_images/404.html +++ /dev/null @@ -1,133 +0,0 @@ - - - - - - - - - Fedora Documentation Website - - - - - - - - - - - -
-
-
- -

Fedora Documentation Site

-
-
-
-
-

Fedora Documentation - 404 Page Not Found :(

-

Hi! You've arrived at Fedora documentation page which does not actually exist. This may be because you followed a link to an older document which has been retired. For reference, you can find those in our old document archive. Or, you can browse current docs.

-

It may also be that this page _should_ exist, but sadly does not. If this is the case, and you know what it should say, you can contribute via the Docs Project.

-
-
-
- -
-
-
-
-
-

About

-
-
-
About Fedora
-
Sponsors
-
Fedora Magazine
-
Legal
-
-
    -
  • - -
    • -
  • - -
    • -
  • - -
    • -
-
-
- -
-

Download

-
-
-
Get Fedora Workstation
-
Get Fedora Server
-
Get Fedora Atomic
-
Fedora Spins
-
Fedora Labs
-
Fedora ARM®
-
Alternative Downloads
- -
-
-
- -
-

Support

-
-
-
Get Help
-
Ask Fedora
-
Common Bugs
-
Fedora Developer Portal
-
Installation Guide
-
-
-
- -
-

Join

-
-
-
Join Fedora
-
Planet Fedora
-
Fedora SIGs
-
Fedora Account System
-
Fedora Community
-
-
-
-
- -
-
-
- -
-
-
-
- - -

© 2017 Red Hat, Inc. and others. Please send any comments or corrections to the websites team

-
-
-
- -
-
-
- - - - - - diff --git a/_images/favicon.ico b/_images/favicon.ico deleted file mode 100644 index a912017..0000000 Binary files a/_images/favicon.ico and /dev/null differ diff --git a/_images/favicon32x32.png b/_images/favicon32x32.png deleted file mode 100644 index d33bd5e..0000000 Binary files a/_images/favicon32x32.png and /dev/null differ diff --git a/_images/fedora.svg b/_images/fedora.svg deleted file mode 100644 index e8fd52b..0000000 --- a/_images/fedora.svg +++ /dev/null @@ -1,61 +0,0 @@ - - - - - - - - - - - - - - - - - - - diff --git a/_images/redhat-logo.png b/_images/redhat-logo.png deleted file mode 100644 index f085f1a..0000000 Binary files a/_images/redhat-logo.png and /dev/null differ diff --git a/_javascripts/.gitkeep b/_javascripts/.gitkeep deleted file mode 100644 index e69de29..0000000 --- a/_javascripts/.gitkeep +++ /dev/null diff --git a/_javascripts/bootstrap-offcanvas.js b/_javascripts/bootstrap-offcanvas.js deleted file mode 100644 index 62cf7b6..0000000 --- a/_javascripts/bootstrap-offcanvas.js +++ /dev/null @@ -1,6 +0,0 @@ -$(document).ready(function () { - $('[data-toggle="offcanvas"]').click(function () { - $('.sidebar').show(); - $('.row-offcanvas').toggleClass('active'); - }); -}); diff --git a/_stylesheets/asciibinder.css b/_stylesheets/asciibinder.css deleted file mode 100644 index e1abf83..0000000 --- a/_stylesheets/asciibinder.css +++ /dev/null @@ -1,573 +0,0 @@ -@import url(https://maxcdn.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css); -/* ------------------------------------------------------------ -Image: "Spin" https://www.flickr.com/photos/eflon/3655695161/ -Author: eflon https://www.flickr.com/photos/eflon/ -License: https://creativecommons.org/licenses/by/2.0/ ----------------------------------------------------------------*/ -.attribution { - text-align: center; - position: relative; - bottom: -20px; -} -.attribution .btn { - color: #808080; - color: rgba(175,175,175, .65); - font-size: 11px; -} -.attribution .btn:hover { - text-decoration: none; - color: #aaa; -} -.popover-content { - font-size: 12px; - line-height: 1.3; - font-weight: normal; -} - -@media screen and (max-width: 980px) { - body { - margin-bottom: 200px; - } - footer { - text-align: center; - } - footer .text-right { - text-align: center !important; - } - #footer_social .first { - margin-left: 0; - } - #footer_social > a { - top: 24px; - } -} - -.fa-inverse:hover { - color: #ccc; -} - -.collapse a.active { - background-color: #DEEAF4; - color: #000; - position: relative; -} - -.collapse a.active:hover { - text-decoration: none; -} - -.collapse a.active:before { - background-color: #A0C3E5; - content: ""; - display: inline-block; - height: 100%; - left: 0; - position: absolute; - top: 0; - width: 3px; -} - -.main h2, .main .h2 { - border-top: 0px; - padding-top: 10px; -} - -.page-header { - height: 100% !important; -} -.page-header .img-responsive { - display: inline; -} -.page-header h2 { - font-size: 28px; - display: inline; - margin-left: 20px; - vertical-align: bottom; -} - -.navbar-brand { - padding: initial; - height: initial; -} - -.nav > li > a.hover{ - background-color: none; -} - -h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 { - position: relative; -} - -h2 > a.anchor, h3 > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { - display: block; - font-weight: normal; - margin-left: -1.5ex; - position: absolute; - text-align: center; - text-decoration: none !important; - visibility: hidden; - width: 1.5ex; - z-index: 1001; -} - -h2 > a.anchor:before, h3 > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { - content: "\f0c1"; - display: block; - font-family: FontAwesome; - font-size: 0.7em; - -webkit-font-smoothing: antialiased; - -moz-osx-font-smoothing: grayscale; - padding-top: 0.2em; -} - -h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { - font-size: 1em; -} - -h2:hover > a.anchor, -h2 > a.anchor:hover, -h3:hover > a.anchor, -h3 > a.anchor:hover, -h4:hover > a.anchor, -h4 > a.anchor:hover, -h5:hover > a.anchor, -h5 > a.anchor:hover, -h6:hover > a.anchor, -h6 > a.anchor:hover { - visibility: visible; -} - -.main { - border-left: 1px solid #e7e7e7; - margin-left: -1px; - padding-left: 25px; -} - - -@media (min-width: 768px) { - .main { - padding-left: 30px; - } -} - -/* - * Sidebar - */ - -.nav-header { - font-size: 16px; -} - -.nav-header ul { - font-size: 14px; -} - -.nav-header ul li a { - display: block; - padding: 5px 20px 5px 25px; - font-size: 13px; - font-weight: normal; -} - -.nav-sidebar .fa { - text-align: center; - top: -1px; - width: 14px; -} - -.nav-sidebar li a { - color: inherit; -} - -.nav-sidebar li a:hover { - color: #000; -} - -.nav-sidebar ul li ul.nav-tertiary li a { - padding-left: 50px; -} - -.nav-sidebar > li > a { - padding: 7px 0; -} - -.nav-sidebar > li > a:focus, .nav-sidebar > li > a:hover { - background: transparent; -} - -.sidebar { - font-weight: 300; - display: none; - padding-top: 13px; -} - -@media screen and (max-width: 767px) { - .sidebar { - padding-left: 30px; - padding-right: 0; - } -} - -@media screen and (min-width: 768px) { - .sidebar { - border-right: 1px solid #e7e7e7; - display: block; - } -} - -/* - * Off Canvas - * -------------------------------------------------- - */ - -body, html { - overflow-x: hidden; /* Prevent scroll on narrow devices */ -} - -.toggle-nav { - margin-right: 20px; -} - -@media screen and (max-width: 767px) { - .row-offcanvas { - position: relative; - -webkit-transition: all .25s ease-out; - -o-transition: all .25s ease-out; - transition: all .25s ease-out; - } - - .row-offcanvas-right { - right: 0; - } - - .row-offcanvas-left { - left: 0; - } - - .row-offcanvas-right - .sidebar-offcanvas { - right: -75%; /* 8 columns */ - } - - .row-offcanvas-left - .sidebar-offcanvas { - left: -75%; /* 8 columns */ - } - - .row-offcanvas-right.active { - right: 75%; /* 8 columns */ - } - - .row-offcanvas-left.active { - left: 75%; /* 8 columns */ - } - - .sidebar-offcanvas { - overflow: hidden; - position: absolute; - top: 0; - width: 75%; /* 8 columns */ - } -} - - p { - margin: 0 0 1.6em; - } - - /* Remnants of Asciidoctor default stylesheet - remove styles as needed */ - -#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; } -.left { float: left !important; } -.right { float: right !important; } -.text-left { text-align: left !important; } -.text-right { text-align: right !important; } -.text-center { text-align: center !important; } -.text-justify { text-align: justify !important; } -.hide { display: none; } -.subheader, #content #toctitle, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #7a2518; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; } -abbr, acronym { text-transform: uppercase; font-size: 90%; color: #333333; border-bottom: 1px dotted #dddddd; cursor: help; } -abbr { text-transform: none; } -blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 3px solid #487c58; } -blockquote cite { display: block; font-size: inherit; color: #454545; } -blockquote cite:before { content: "\2014 \0020"; } -blockquote cite a, blockquote cite a:visited { color: #454545; } -blockquote, blockquote p { line-height: 1.6; color: #6e6e6e; } -@media only screen and (min-width: 768px) { - #toctitle, .sidebarblock > .content > .title { line-height: 1.4; } - #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } -} -table { background: white; margin-bottom: 1.25em; border: solid 1px #dddddd; } -table thead, table tfoot { background: whitesmoke; font-weight: bold; } -table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #333333; text-align: left; } -table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #333333; } -table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f9f9f9; } -table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.6; } -.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; } -.clearfix:after, .float-group:after { clear: both; } -*:not(pre) > code { font-size: inherit; padding: 0; white-space: nowrap; background-color: inherit; border: 0 solid #dddddd; -webkit-border-radius: 4px; border-radius: 4px; text-shadow: none; line-height: 1; } -.keyseq { color: #666666; } -kbd:not(.keyseq) { display: inline-block; color: #333333; font-size: 0.75em; line-height: 1.4; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; } -.keyseq kbd:first-child { margin-left: 0; } -.keyseq kbd:last-child { margin-right: 0; } -.menuseq, .menu { color: #1a1a1a; } -b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; } -b.button:before { content: "["; padding: 0 3px 0 2px; } -b.button:after { content: "]"; padding: 0 2px 0 3px; } -p a > code:hover { color: #561309; } -#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; } -#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; } -#header:after, #content:after, #footnotes:after, #footer:after { clear: both; } -#content:before { content: none; } -#header { margin-bottom: 2.5em; } -#header > h1 { color: black; font-weight: 300; border-bottom: 1px solid #d8d8d8; margin-bottom: -28px; padding-bottom: 32px; } -#header span { color: #6e6e6e; } -#header #revnumber { text-transform: capitalize; } -#header br { display: none; } -#header br + span { padding-left: 3px; } -#header br + span:before { content: "\2013 \0020"; } -#header br + span.author { padding-left: 0; } -#header br + span.author:before { content: ", "; } -#toc { border-bottom: 3px double #e5e5e5; padding-top: 1em; padding-bottom: 1.25em; } -#toc > ul { margin-left: 0.25em; } -#toc ul.sectlevel0 > li > a { font-style: italic; } -#toc ul.sectlevel0 ul.sectlevel1 { margin-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } -#toc ul { font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; list-style-type: none; } -#toc a { text-decoration: none; } -#toc a:active { text-decoration: underline; } -#toctitle { color: #7a2518; } -@media only screen and (min-width: 768px) { body.toc2 { padding-left: 15em; padding-right: 0; } - #toc.toc2 { background-color: #fafaf9; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #e5e5e5; border-bottom: 0; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; } - #toc.toc2 #toctitle { margin-top: 0; font-size: 1.2em; } - #toc.toc2 > ul { font-size: .90em; margin-bottom: 0; } - #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } - #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } - body.toc2.toc-right { padding-left: 0; padding-right: 15em; } - body.toc2.toc-right #toc.toc2 { border-right: 0; border-left: 1px solid #e5e5e5; left: auto; right: 0; } } -@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } - #toc.toc2 { width: 20em; } - #toc.toc2 #toctitle { font-size: 1.375em; } - #toc.toc2 > ul { font-size: 0.95em; } - #toc.toc2 ul ul { padding-left: 1.25em; } - body.toc2.toc-right { padding-left: 0; padding-right: 20em; } } -#content #toc { border-style: solid; border-width: 1px; border-color: #e3e3dd; margin-bottom: 1.25em; padding: 1.25em; background: #fafaf9; border-width: 0; -webkit-border-radius: 4px; border-radius: 4px; } -#content #toc > :first-child { margin-top: 0; } -#content #toc > :last-child { margin-bottom: 0; } -#content #toctitle { font-size: 1.375em; } -#footer { max-width: 100%; background-color: #333333; padding: 1.25em; } -#footer-text { color: #cccccc; line-height: 1.44; } -.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .verseblock, .videoblock { margin-bottom: 2.5em; } -.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; font-family: "Noto Serif", "DejaVu Serif", "Serif", serif; font-weight: normal; font-style: italic; } -table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; } -table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; } -.admonitionblock > table { border: 0; background: none; width: 100%; } -.admonitionblock > table td.icon { text-align: center; width: 80px; } -.admonitionblock > table td.icon img { max-width: none; } -.admonitionblock > table td.icon .title { font-weight: 300; text-transform: uppercase; } -.admonitionblock > table td.content { padding-left: 0; padding-right: 1.25em; color: #6e6e6e; } -.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; } -.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 4px; border-radius: 4px; } -.exampleblock > .content > :first-child { margin-top: 0; } -.exampleblock > .content > :last-child { margin-bottom: 0; } -.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { color: #333333; } -.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { line-height: 1; margin-bottom: 0.625em; } -.exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { line-height: 1.4; } -.exampleblock.result > .content { -webkit-box-shadow: 0 1px 8px #e3e3dd; box-shadow: 0 1px 8px #e3e3dd; } -.sidebarblock { border-style: solid; border-width: 1px; border-color: #e3e3dd; margin-top: -1.0em; margin-bottom: 1.6em; padding: .5em; background: #F1F3F5; -webkit-border-radius: 4px; border-radius: 4px; overflow-x: auto; } -.sidebarblock > :first-child { margin-top: 0; } -.sidebarblock > :last-child { margin-bottom: 0; } -.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { color: #333333; } -.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { line-height: 1; margin-bottom: 0.625em; } -.sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { line-height: 1.4; } -.sidebarblock > .content > .title { color: #7a2518; margin-top: 0; line-height: 1.6; } -.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; } -.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 0px; background-color: #F0F3F5; -webkit-border-radius: 5px; border-radius: 5px; padding: 1.5em 2.5em; word-wrap: break-word; } -.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; } -.literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { display: block; } -.listingblock > .content { position: relative; } -.listingblock:hover code[class*=" language-"]:before { text-transform: uppercase; font-size: 0.9em; color: #999; position: absolute; top: 0.375em; right: 0.375em; } -.listingblock:hover code.asciidoc:before { content: "asciidoc"; } -.listingblock:hover code.clojure:before { content: "clojure"; } -.listingblock:hover code.css:before { content: "css"; } -.listingblock:hover code.go:before { content: "go"; } -.listingblock:hover code.groovy:before { content: "groovy"; } -.listingblock:hover code.html:before { content: "html"; } -.listingblock:hover code.java:before { content: "java"; } -.listingblock:hover code.javascript:before { content: "javascript"; } -.listingblock:hover code.python:before { content: "python"; } -.listingblock:hover code.ruby:before { content: "ruby"; } -.listingblock:hover code.sass:before { content: "sass"; } -.listingblock:hover code.scss:before { content: "scss"; } -.listingblock:hover code.xml:before { content: "xml"; } -.listingblock:hover code.yaml:before { content: "yaml"; } -.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; } -.listingblock.terminal pre .command:not([data-prompt]):before { content: '$'; } -table.pyhltable { border: 0; margin-bottom: 0; } -table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; } -table.pyhltable td.code { padding-left: .75em; padding-right: 0; } -.highlight.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #d8d8d8; } -.highlight.pygments .lineno { display: inline-block; margin-right: .25em; } -table.pyhltable .linenodiv { background-color: transparent !important; padding-right: 0 !important; } -.quoteblock { margin: 0 0 1.25em 0; padding: 0.5625em 1.25em 0 1.1875em; border-left: 3px solid #487c58; } -.quoteblock blockquote { margin: 0 0 1.25em 0; padding: 0 0 0.625em 0; border: 0; } -.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; } -.quoteblock .attribution { margin-top: -0.625em; padding-bottom: 0.625em; font-size: inherit; color: #454545; line-height: 1.6; } -.quoteblock .attribution br { display: none; } -.quoteblock .attribution cite { display: block; } -table.tableblock { max-width: 100%; } -table.tableblock td .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; } -table.spread { width: 100%; } -table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dddddd; } -table.grid-all th.tableblock, table.grid-all td.tableblock { border-width: 0 1px 1px 0; } -table.grid-all tfoot > tr > th.tableblock, table.grid-all tfoot > tr > td.tableblock { border-width: 1px 1px 0 0; } -table.grid-cols th.tableblock, table.grid-cols td.tableblock { border-width: 0 1px 0 0; } -table.grid-all * > tr > .tableblock:last-child, table.grid-cols * > tr > .tableblock:last-child { border-right-width: 0; } -table.grid-rows th.tableblock, table.grid-rows td.tableblock { border-width: 0 0 1px 0; } -table.grid-all tbody > tr:last-child > th.tableblock, table.grid-all tbody > tr:last-child > td.tableblock, table.grid-all thead:last-child > tr > th.tableblock, table.grid-rows tbody > tr:last-child > th.tableblock, table.grid-rows tbody > tr:last-child > td.tableblock, table.grid-rows thead:last-child > tr > th.tableblock { border-bottom-width: 0; } -table.grid-rows tfoot > tr > th.tableblock, table.grid-rows tfoot > tr > td.tableblock { border-width: 1px 0 0 0; } -table.frame-all { border-width: 1px; } -table.frame-sides { border-width: 0 1px; } -table.frame-topbot { border-width: 1px 0; } -th.halign-left, td.halign-left { text-align: left; } -th.halign-right, td.halign-right { text-align: right; } -th.halign-center, td.halign-center { text-align: center; } -th.valign-top, td.valign-top { vertical-align: top; } -th.valign-bottom, td.valign-bottom { vertical-align: bottom; } -th.valign-middle, td.valign-middle { vertical-align: middle; } -table thead th, table tfoot th { font-weight: bold; } -tbody tr th { display: table-cell; line-height: 1.6; background: whitesmoke; } -tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #333333; font-weight: bold; } -td > div.verse { white-space: pre; } -ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; } -ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; } -ul.checklist li > p:first-child > .fa-check-square-o:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; } -ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; } -ul.inline { margin: 0 auto 0.625em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; } -ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; } -ul.inline > li > * { display: block; } -.unstyled dl dt { font-weight: normal; font-style: normal; } -ol.arabic { list-style-type: decimal; } -ol.decimal { list-style-type: decimal-leading-zero; } -ol.loweralpha { list-style-type: lower-alpha; } -ol.upperalpha { list-style-type: upper-alpha; } -ol.lowerroman { list-style-type: lower-roman; } -ol.upperroman { list-style-type: upper-roman; } -ol.lowergreek { list-style-type: lower-greek; } -.hdlist > table, .colist > table { border: 0; background: none; } -.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; } -td.hdlist1 { padding-right: .75em; font-weight: bold; } -td.hdlist1, td.hdlist2 { vertical-align: top; } -.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; } -.colist > table tr > td:first-of-type { padding: 0 .75em; line-height: 1; } -.colist > table tr > td:last-of-type { padding: 0.25em 0; } -.qanda > ol > li > p > em:only-child { color: #1d4b8f; } -.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; } -.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; } -.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; } -.imageblock > .title { margin-bottom: 0; } -.imageblock.thumb, .imageblock.th { border-width: 6px; } -.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; } -.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; } -.image.left { margin-right: 0.625em; } -.image.right { margin-left: 0.625em; } -a.image { text-decoration: none; } -span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; } -span.footnote a, span.footnoteref a { text-decoration: none; } -span.footnote a:active, span.footnoteref a:active { text-decoration: underline; } -#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; } -#footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; } -#footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; } -#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; } -#footnotes .footnote:last-of-type { margin-bottom: 0; } -#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; } -.gist .file-data > table { border: none; background: #fff; width: 100%; margin-bottom: 0; } -.gist .file-data > table td.line-data { width: 99%; } -div.unbreakable { page-break-inside: avoid; } -.replaceable { font-style: italic; font-color: inherit; font-family: inherit; } -.parameter { font-style: italic; font-family: monospace; } -.userinput { font-weight: bold; font-family: monospace; } -.envar { font-weight: bold; font-family: monospace; font-size: 90%; } -.sysitem { font-weight: bold; font-size: 90%; } -.package { font-weight: bold; font-size: 90%; } -.filename { font-weight: bold; font-style: italic; font-size: 90%; } -.big { font-size: larger; } -.small { font-size: smaller; } -.underline { text-decoration: underline; } -.overline { text-decoration: overline; } -.line-through { text-decoration: line-through; } -.aqua { color: #00bfbf; } -.aqua-background { background-color: #00fafa; } -.black { color: black; } -.black-background { background-color: black; } -.blue { color: #0000bf; } -.blue-background { background-color: #0000fa; } -.fuchsia { color: #bf00bf; } -.fuchsia-background { background-color: #fa00fa; } -.gray { color: #606060; } -.gray-background { background-color: #7d7d7d; } -.green { color: #006000; } -.green-background { background-color: #007d00; } -.lime { color: #00bf00; } -.lime-background { background-color: #00fa00; } -.maroon { color: #600000; } -.maroon-background { background-color: #7d0000; } -.navy { color: #000060; } -.navy-background { background-color: #00007d; } -.olive { color: #606000; } -.olive-background { background-color: #7d7d00; } -.purple { color: #600060; } -.purple-background { background-color: #7d007d; } -.red { color: #bf0000; } -.red-background { background-color: #fa0000; } -.silver { color: #909090; } -.silver-background { background-color: #bcbcbc; } -.teal { color: #006060; } -.teal-background { background-color: #007d7d; } -.white { color: #bfbfbf; } -.white-background { background-color: #fafafa; } -.yellow { color: #bfbf00; } -.yellow-background { background-color: #fafa00; } -span.icon > .fa { cursor: default; } -.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; cursor: default; } -.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #4E9FDD; } -.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; color: #2C8596; } -.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #ec7a08; } -.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #ec7a08; } -.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #c00; } -.conum[data-value] { display: inline-block; color: white !important; background-color: #333333; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; width: 20px; height: 20px; font-size: 12px; line-height: 20px; font-family: "Open Sans", "Sans", sans-serif; font-style: normal; font-weight: bold; text-indent: -1px; } -.conum[data-value] * { color: white !important; } -.conum[data-value] + b { display: none; } -.conum[data-value]:after { content: attr(data-value); } -pre .conum[data-value] { position: relative; top: -2px; } -b.conum * { color: inherit !important; } -.conum:not([data-value]):empty { display: none; } -.print-only { display: none !important; } -@media print { @page { margin: 1.25cm 0.75cm; } - * { -webkit-box-shadow: none !important; box-shadow: none !important; text-shadow: none !important; } - a, a:visited { color: inherit !important; text-decoration: underline !important; } - a[href^="http:"]:after, a[href^="https:"]:after { content: " (" attr(href) ")"; } - a[href^="#"], a[href^="#"]:visited, a[href^="mailto:"], a[href^="mailto:"]:visited { text-decoration: none !important; } - abbr[title]:after { content: " (" attr(title) ")"; } - pre, blockquote { page-break-inside: avoid; } - code { color: #191919; } - thead { display: table-header-group; } - tr, img { page-break-inside: avoid; } - img { max-width: 100% !important; } - p { orphans: 3; widows: 3; } - h2, h3, #toctitle, .sidebarblock > .content > .title, #toctitle, .sidebarblock > .content > .title { page-break-after: avoid; } - #toc, .sidebarblock { background: none !important; } - #toc { border-bottom: 1px solid #d8d8d8 !important; padding-bottom: 0 !important; } - .sect1 { padding-bottom: 0 !important; } - .sect1 + .sect1 { border: none !important; } - body.book #header { text-align: center; } - body.book #header > h1 { border: none !important; margin: 2.5em 0 1em 0; padding: 0; } - body.book #header span { line-height: 1.6; } - body.book #header br { display: block; } - body.book #header br + span { padding-left: 0; } - body.book #header br + span:before { content: none !important; } - body.book #toc { border: none !important; text-align: left !important; padding: 0 !important; } - #footer { background: none !important; } - #footer-text { color: #333333 !important; } - .hide-on-print { display: none !important; } - .print-only { display: block !important; } - .hide-for-print { display: none !important; } - .show-for-print { display: inherit !important; } } diff --git a/_templates/_css.html.erb b/_templates/_css.html.erb deleted file mode 100644 index 0fca7ae..0000000 --- a/_templates/_css.html.erb +++ /dev/null @@ -1,3 +0,0 @@ -<%- Dir.glob("_stylesheets/*").sort.each do |sheet| -%> - -<%- end -%> diff --git a/_templates/_nav.html.erb b/_templates/_nav.html.erb deleted file mode 100644 index 95a7e5c..0000000 --- a/_templates/_nav.html.erb +++ /dev/null @@ -1,31 +0,0 @@ - diff --git a/_templates/page.html.erb b/_templates/page.html.erb deleted file mode 100644 index b9a30ac..0000000 --- a/_templates/page.html.erb +++ /dev/null @@ -1,181 +0,0 @@ - - - - - - - <%= distro %> <%= version %> | <%= [group_title, subgroup_title, topic_title].compact.join(' | ') %> - - - - - - <%= render("_templates/_css.html.erb", :css_path => css_path) %> - - - - - - " rel="shortcut icon" type="text/css"> - - - - - -
-

- -

-
    -
  1. - <%= site_name %> -
    2. - - - <%= breadcrumb_subgroup_block %> - -
-
-
- <%= render("_templates/_nav.html.erb", :navigation => navigation, :group_id => group_id, :topic_id => topic_id, :subgroup_id => subgroup_id, :subtopic_shim => subtopic_shim) %> -
-
-
-

<%= article_title %>

-
- <%= content %> -
-
-
-
-
-
-
-
-

About

-
-
-
About Fedora
-
Sponsors
-
Fedora Magazine
-
Legal
-
-
    -
  • - -
    • -
  • - -
    • -
  • - -
    • -
-
-
- -
-

Download

-
-
-
Get Fedora Workstation
-
Get Fedora Server
-
Get Fedora Atomic
-
Fedora Spins
-
Fedora Labs
-
Fedora ARM®
-
Alternative Downloads
- -
-
-
- -
-

Support

-
-
-
Get Help
-
Ask Fedora
-
Common Bugs
-
Fedora Developer Portal
-
Installation Guide
-
-
-
- -
-

Join

-
-
-
Join Fedora
-
Planet Fedora
-
Fedora SIGs
-
Fedora Account System
-
Fedora Community
-
-
-
-
- -
-
-
- " alt="Red Hat Logo" /> -
-
-
-
- - -

© 2017 Red Hat, Inc. and others. Please send any comments or corrections to the websites team

-
-
-
- -
-
-
- - - - - - - - diff --git a/_topic_map.yml b/_topic_map.yml deleted file mode 100644 index 56501e0..0000000 --- a/_topic_map.yml +++ /dev/null @@ -1,57 +0,0 @@ -# This configuration file dictates the organization of the topic groups and -# topics on the main page of the doc site for this branch. Each record -# consists of the following: -# -# --- <= Record delimiter -# Name: Origin of the Species <= Display name of topic group -# Dir: origin_of_the_species <= Directory name of topic group -# Topics: -# - Name: The Majestic Marmoset <= Topic name -# File: the_majestic_marmoset <= Topic file under group dir +/- -# - Name: The Curious Crocodile <= Topic 2 name -# File: the_curious_crocodile <= Topic 2 file -# - Name: The Numerous Nematodes <= Sub-topic group name -# Dir: the_numerous_nematodes <= Sub-topic group dir -# Topics: -# - Name: The Wily Worm <= Sub-topic name -# File: the_wily_worm <= Sub-topic file under / -# - Name: The Acrobatic Ascarid <= Sub-topic 2 name -# File: the_acrobatic_ascarid <= Sub-topic 2 file under / -# -# The ordering of the records in this document determines the ordering of the -# topic groups and topics on the main page. ---- -Name: Fedora Documentation Guide -Dir: en-US -Topics: - - Name: Contributing - File: index - - Name: Pull Requests - File: pr - - Name: Publishing Translations - File: publishing-translation - - Name: Organization - File: repo-org - - Name: Tools - File: tools - - Name: Documentation Format - File: writing-format - - Name: Documentation Markup - File: writing-markup - - Name: Style Guide - Dir: style-guide - Topics: - - Name: Introduction to the Style Guide - File: introduction - - Name: General Writing Guidelines - File: writing-guidelines - - Name: Syntax and Language Usage - File: syntax-usage - - Name: Dates and Times - File: dates-times - - Name: Numbers - File: numbers - - Name: Abbreviations - File: abbreviations - - Name: Lists - File: lists diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..a578f9f --- /dev/null +++ b/antora.yml @@ -0,0 +1,6 @@ +name: documentation-guide +title: Documentation Guide +version: master +start_page: ROOT:index +nav: +- modules/ROOT/nav.adoc diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..c9349e3 --- /dev/null +++ b/build.sh @@ -0,0 +1,16 @@ +#!/bin/sh + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + docker run --rm -it -v $(pwd):/antora antora/antora --html-url-extension-style=indexify site.yml + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Let's assume that it's running the Docker deamon + # which requires root. + echo "" + echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it." +sudo docker run --rm -it -v $(pwd):/antora:z antora/antora --html-url-extension-style=indexify site.yml +fi diff --git a/en-US/.gitkeep b/en-US/.gitkeep deleted file mode 100644 index e69de29..0000000 --- a/en-US/.gitkeep +++ /dev/null diff --git a/en-US/index.adoc b/en-US/index.adoc deleted file mode 100644 index 234be01..0000000 --- a/en-US/index.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Contribute to Fedora documentation - -== Different ways to contribute - -There are a few different ways you can contribute to Fedora documentation. -While all of these are great ways to contribute, we've listed them in the order of maximum impact. - -* To do the work yourself, or if it is a substantial change, you should clone the repository, make your changes, and submit a pull request (PR). -Each PR should have closely-related changes. -In particular, it is a good idea to use separate PRs for bug-fix changes (for an old or current release) vs enhancement changes (for an upcoming new release). -Further information about link:pr.html[PRs is available]. - -* Create an issue in https://pagure.io/[pagure.io] in the repository of the appropriate document. -See the link:#repository-list[Fedora Docs repository list] below for more details. - -* Email the Fedora documentation team: docs@lists.fedoraproject.org. - - -[[repository-list]] -== Repository list - -Major documents or documentation sets are separated into separate repositories. -All repositories are stored in https://pagure.io/[pagure.io]. - -The major documents and documentations sets are: - -* Release Notes - https://pagure.io/fedora-docs/release-notes -* Installation Guide - https://pagure.io/fedora-docs/install-guide -* System Administrator's Guide - https://pagure.io/fedora-docs/system-administrators-guide - -This document is stored in https://pagure.io/fedora-docs/documentation-guide. diff --git a/en-US/pr.adoc b/en-US/pr.adoc deleted file mode 100644 index 474ad66..0000000 --- a/en-US/pr.adoc +++ /dev/null @@ -1,95 +0,0 @@ -= Understanding pull-request workflow - -Fedora documentation uses Git to store source files and facilitate collaboration. Using so-called pull requests is an established workflow for the Git version control system. This section provides basic guidelines for Git use and outlines a workflow to be followed when working with documentation repositories. - -== Guidelines - -Learn about basic best practices to make collaboration streamlined. - -=== Keep writing - -Provide a clear statement of the changes that are included in the _pull request_ (PR). -This will help the right people see your changes and will aid in getting them reviewed faster. - -=== Keep it small - -Giant dumps or edits make reviews a lengthy and time consuming process. -For the sake of the review and yourself, keep PRs as small as you can while still making sense. - -To provide a large number of edits to existing documents, group them by section, or by the type of correction you are making. -If you are adding new content keep limit each PR to a new page or section. - -However, each PR must be fully self-contained. -The balance you want to strike is between readability and manageability of the PR; ensuring that each PR, when committed, leaves the documentation logical and complete. - -=== Keep it clean - -Histories are an extremely valuable part of using a version control system, but providing a history of your small changes may not be as useful. -If you are the type of person who commits often locally, and you tend to have lots of commits making up your PRs, look at using `git{nbsp}rebase` to combine commits into a smaller number of more verbose commits. - -=== Keep paying attention - -As the PR submitter, your job is not done once you start the process. -Make sure to stay engaged and work with the people reviewing your changes. - -=== Keep a good attitude - -After putting a lot of work into something, it is natural to take reviews as a personal attack. -Try and remember that this process is designed to help create the best possible end-product for Fedora. -It is important to keep that in mind and not to let it discourage you from continuing. - -=== Keep it legal - -FIXME: If you're referencing a third-party repo or other proprietary software, please include the third-party legal admonition at the top of the page. - -== Workflow - -The sources for Fedora's documentation are stored in Git repositories at link:https://pagure.io[pagure.io]. -Contributions are accepted via _pull requests_, which merge changes from your copy of the repository into the original. - -. Install the required link:tools.html[tools]. - -. Log into Pagure and click the *Fork* button in the upper right-hand corner of a repository. -You now have a personal copy of the repo, called a _fork_. - -. Clone your fork of the repository using the *SSH* URL. -+ -.... -$ git clone ssh://git@pagure.io/forks//documentation-guide.git -$ cd documentation-guide -.... - -. Create a branch to contain your work. -This makes it easier for others to pull from your repo without disrupting their existing content. -You can name the branch anything, but something that correlates to the work you'll be doing is best. -+ -.... -$ git checkout -b pull_request_workflow -.... - -. Make your changes using the editor of your choice. Add a commit for each distinct change. -+ -.... -$ git add en-US/pr.adoc -$ git commit -m 'begin describing pull request workflow' -.... - -. #FIXME# - how to build previews - -. Push your changes to Pagure. -+ -.... -$ git push origin -.... - -. #FIXME# - add how to keep your branch up to date with other changes while working and how to do a final rebase to avoid merge conflicts (by adding a `git remote`). - -. #FIXME# - add how to squash commits. - -. The new branch will now appear in your fork on pagure. -Once you have pushed a cohesive set of changes, press the *New PR* button to start a new pull request. -Pagure will send your changes for review after you fill out the form and press *Create*. - -. Work with your reviewer to address any concerns. Subsequent commits pushed to this branch of your fork will be automatically included in the pull request. - -. Your changes get merged by the reviewer. Congratulations! Reward yourself with your favorite treat, you've earned it! Soon you'll also earn a link:https://badges.fedoraproject.org/[Fedora Badge]. diff --git a/en-US/publishing-translation.adoc b/en-US/publishing-translation.adoc deleted file mode 100644 index 7026eee..0000000 --- a/en-US/publishing-translation.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Publishing - -FIXME - Document final publishing tool and translation hand-off diff --git a/en-US/repo-org.adoc b/en-US/repo-org.adoc deleted file mode 100644 index fd7a9a8..0000000 --- a/en-US/repo-org.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[[repository-organization]] -== Repository Organization - -Major documents and/or documentation sets are separated -into separate repositories. All repositories are stored in -https://pagure.io/[pagure.io]. - -FIXME document repository structure - -* Files in every repo -* branches are versions -* master latest "rawhide" documentation diff --git a/en-US/style-guide/abbreviations.adoc b/en-US/style-guide/abbreviations.adoc deleted file mode 100644 index 5c7cec2..0000000 --- a/en-US/style-guide/abbreviations.adoc +++ /dev/null @@ -1,54 +0,0 @@ -== Abbreviations - -=== The United States - -As a noun appearing alone, use `United States`. - ----- -...the government of the United States... ----- - -As a noun appearing as part of a locality, use `US` with no periods and no spaces. - ----- -Raleigh, NC, US -US, Earth ----- - -As an adjective, use `U.S.` with no spaces. - ----- -...the U.S. government... ----- - -==== States - -Spell out state names when they appear alone. - ----- -...the government of North Carolina... ----- - -When abbreviating state names, use their two-letter ZIP standard abbreviations. - -Abbreviate state names when they appear as part of a locality. - ----- -Raleigh, NC ----- - -Place one comma between the city and state name and another after the state name, unless it ends the sentence or is part of a dateline. - ----- -...founded in Raleigh, NC, by Red Hat... -...managed from Raleigh, NC. ----- - -=== Academic Degrees - -* Avoid abbreviating degrees. -* Use an apostrophe in bachelor's degree, master's, etc. -* Do not use an apostrophe in Bachelor of Arts, Master of Science, etc. -* Use abbreviations only when the preferred method would be cumbersome. -* Use abbreviations only after a full name. -* Set abbreviations apart with commas. diff --git a/en-US/style-guide/dates-times.adoc b/en-US/style-guide/dates-times.adoc deleted file mode 100644 index af9409c..0000000 --- a/en-US/style-guide/dates-times.adoc +++ /dev/null @@ -1,63 +0,0 @@ -== Dates and Times - -The styles used for dates and times vary widely around the world, and this creates a lot of confusion. -While there is consensus on one calendar for most business purposes, the dates on this calendar can be represented in many different ways. -The varying uses of daylight saving time and assorted ways of representing time can make even simple communications more difficult. -International standards have been developed to effectively communicate dates and times, and these standards should be used for publications that may reach a global audience. - -Absolute dates and times specify specific points in time and may include points in the past, present, or future. - -The ISO 8601 standard provides a simple way to represent dates and times that is easily recognized around the world and is equally easy to use. -Under this standard, all values are ordered from most to least significant. -Write all absolute dates and times in accordance with the ISO 8601 standard. - -=== Dates - -Use the following guidelines when writing general dates: - -* Spell out days of the week and separate them from dates using a comma. -* When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD) to avoid confusion. -* When listing a day and month: -** List the day first. -** Spell out the day. -** Set the day and month apart with `of`. -** Spell out the month. -* When listing a month and year: -** List the month first. -** Spell out the month. -** Set the month and year apart with `of`. -** Use Arabic numerals for the year. - -.Examples ----- -Sunday, 2000-01-01 -2000-01-01 -The first of January -January of 2000 ----- - -=== Times - -Use the following guidelines when writing general times: - -* Use 24-hour time formats. -* Always use units. -* Follow absolute times with a timezone specification. -* Separate days, hours, minutes and seconds with a colon and no spaces. -* Separate seconds and fractions thereof with periods. -* If the scope of a specification is unclear, increase the precision or specify the scope of the lowest precision. -* Use Coordinated Universal Time (UTC) for all worldwide events. -The Coordinated Universal Time (UTC) is a universally recognized time standard and is preferred for time specifications. -This is sometimes referred to as Greenwich Mean Time (GMT) or Zulu Time (Z). -The preferred way to specify a time in UTC is to follow the time with a space and `UTC`. -* Localized events may be specified using UTC or the local time, but always specify a timezone or offset. - -.Examples ----- -15:00 UTC -1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second) -15:00 minutes (15 minutes) -15:30 hours (15 hours and 30 minutes) -The global conference will take place at 15:00 UTC. -The event will be in Raleigh, NC, and will take place at 11:00 UTC-4. ----- diff --git a/en-US/style-guide/introduction.adoc b/en-US/style-guide/introduction.adoc deleted file mode 100644 index d94980a..0000000 --- a/en-US/style-guide/introduction.adoc +++ /dev/null @@ -1,10 +0,0 @@ -== Introduction to the Style Guide - -Writing high-quality documention is a challenge. -In order to provide consistent, readable documentation, Fedora provides this style guide as a standard. -The style guide aims to increase readability and comprehension for users and developers of Fedora, who come from a wide variety of backgrounds and experiences. - -This style guide may vary from each contributor's familiar writing style. -The Fedora Documentation Style Guide borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. -Any differences from those guides are intended to enhance the value of documents for international readers, and accommodate the technical nature of Fedora documentation. -Particular care is made to adopt international standards for common notations to avoid confusion across cultural lines. diff --git a/en-US/style-guide/lists.adoc b/en-US/style-guide/lists.adoc deleted file mode 100644 index de796d6..0000000 --- a/en-US/style-guide/lists.adoc +++ /dev/null @@ -1,9 +0,0 @@ -== Lists -Capitalize and use periods when the list items are complete sentences. -Make them agree so that there aren't a mixture of sentences and fragments. - -You could also have a list with a colon: - -* that was lowercase and not punctuated -* that again doesn't mix forms -* that is likely very short diff --git a/en-US/style-guide/numbers.adoc b/en-US/style-guide/numbers.adoc deleted file mode 100644 index 5c7d876..0000000 --- a/en-US/style-guide/numbers.adoc +++ /dev/null @@ -1,50 +0,0 @@ -== Numbers - -=== When to Spell Out a Number - -Rules for using Arabic numerals or spelling out numbers are as follows and are listed from highest priority to lowest. - -* If the number is part of a casual expression, spell it out. -* If the number is a calendar year, do not spell it out. -* If the number is an age or percentage, do not spell it out. -* If the number begins a sentence, spell it out. -Awkward sentences should be reformed. -* If the number is greater than 10, do not spell it out. -* If the number is one through nine, spell it out. - -.Examples ----- -Five horses ran in the field. -Fedora 27 was released in 2017. -I cannot eat 27 slices of pizza. -I built eight packages for Fedora. ----- - -=== When to Use Roman Numerals - -Use Roman numerals for wars and honorific suffixes. - -.Examples ----- -World War II -John Doe III ----- - -=== Cardinal Numbers and Ordinal Numbers - -Cardinal numbers include figures 1, 2, 10, 101, and so on, and the corresponding words. - -Ordinal numbers include the terms 1st, 2nd, 10th, 101st, and so on, and the corresponding words. - -=== Large Numbers - -When spelling out large numbers, connect words ending in 'y' to subsequent words within the same number with a hyphen. -Avoid commas between words that are part of one number. - -.Examples ----- -twenty-one -one hundred thirty-one -twenty-five thousand one hundred thirty-one -ninety bottles ----- diff --git a/en-US/style-guide/syntax-usage.adoc b/en-US/style-guide/syntax-usage.adoc deleted file mode 100644 index f4916e7..0000000 --- a/en-US/style-guide/syntax-usage.adoc +++ /dev/null @@ -1,132 +0,0 @@ -== Syntax and Language Usage - -=== Contractions - -Avoid contractions, the combination of two words with an apostrophe replacing one or more letters. -Contractions reduce the readability of documents and make translation more difficult. -Other cultures and languages interpret contractions differently, and this confusion conflicts with the goals of the Fedora documentation. - -=== Pronouns - -Pronouns are words that languages use to replace specific noun phrases. -Good writers must strike a balance between over-repeating a noun phrase, and using pronouns to stand in for nouns. -A general rule to preserve clarity is to never repeat noun substitution with a pronoun in two consecutive sentences. -Readers of technical documents need constant reminders on the exact subject the author is referring to. -The over-use of pronouns causes readers to make a guess about the subject a sentence. -These assumptions reduce the effectiveness of documentation. - -Avoid most personal pronouns in documentation, including the following: - -* Subjective personal pronouns ("I," "he," "she," "it," "we,") -* Objective personal pronouns ("me," "her," "him," "us") -* Possessive personal pronouns ("my," "her," "his," "our") - -Also avoid: - -* Reflexive pronouns, such as "yourself" or "himself" -* Intensive pronouns, such as "he himself" or "(you) do it yourself" -* Resist overuse of "you", "your", and "one/one's" - -Occasionally situations require the second personal pronoun "you," and its attendant forms for clarity. -Maintaining an active voice is paramount over avoiding the second personal pronouns. -"You" and "your" are appropriate words to indicate action or possession on the part of the reader. - -Indefinite pronouns such as "this" or "that" without an antecedent make it tough for a reader to follow an author's meaning. -Favor writing an exact noun phrase whenever possible over the vague words "this," "these," "those," and "that." - -.Example -[horizontal] -Incorrect:: Edit your DNF configuration files to use geographically close mirrors. -This allows you to update your system faster. -Correct:: Edit the DNF configuration files to use geographically close mirrors for faster system updates. - -When eliminating indefinite pronouns, a long sentence may result from joining too many clauses. -Use indefinite pronouns to break long sentences up to improve clarity, but always provide a proper antecedent. - -.Example -[horizontal] -Incorrect:: Stay current with recommended updates to your operating system in order to improve functionality of applications, remove security risks, and automatically resolve performance issues solved from bug reports. -Correct:: Stay current with recommended updates to your operating system. -These updates improve functionality of applications, remove security risks, and automatically resolve performance issues solved from bug reports. - -=== Sentence Formation - -Keep sentences as short as possible. -Cutting unnecessary words is vital to strengthen meaning. -There are a number of common traps technical writers fall into resulting in lengthy sentences. - -==== Indirect Discourse - -Indirect discourse refers to the use of "that" to attribute a statement, fact, or feeling in a sentence without the use of quotation marks. -In regular writing, it weakens statements of fact. -Documentation writers can improve the impact of sentences by removing "that" and "which". - -.Example -[horizontal] -Incorrect:: Fedora is an operating system that is upstream for many other open source projects. -Correct:: Fedora is an upstream operating system for many other open source projects. - - -==== Other Unnecessary Word Combinations - -Avoid using the unnecessary word "then" following an "if" statement. -When a sentence begins with an "if" statement, follow it with a comma and complete the sentence with a full statement. - -.Example -[horizontal] -Incorrect:: If an email client will not send or receive messages, then check under the File Menu and verify "Work Offline" mode is unselected. -Correct:: If an email client will not send or receive messages, check under the File Menu and -verify "Work Offline" mode is unselected. - -Many words we use in everyday conversation reduce impact in printed materials because they "leave a way out." These are words preceding verbs and nouns to minimize the sentence's influence. -This is not an exhaustive list, but mindful documentation writers will reduce using these words and those of a similar nature. - -[WARNING] -.Avoid Reducing Impact With Unnecessary Words -==== -The following words minimize the impact of the verb or noun clause within a sentence. -Other words also fit into this category, but this short list is aimed at helping documentation writers identify words of this nature and eliminate them from their writing: *should, could, may, might, perhaps, some, many, most, numerous, few, somewhat, whatever, possibly, can, occasionally,* and *frequently*. -==== - - -==== Sentence Variation - -For the strongest impact, keep the first and last sentences of a paragraph as short as possible. -Varying sentence length within a paragraph and through the entire document keeps a reader's attention. -A short and simple fact is easy to grasp. -There is nothing wrong with using longer sentences to explain complex ideas and concepts, and long as they are still clear. -Try to use a simple synopsis sentence at the end of each paragraph to give readers a reprieve and recap of any important information. -A short final sentence stays with the reader to the next section. - -=== Capitalization - -In sentences, capitalize the first word. Do not start sentences with a command, package, or option name. - -.Example -[horizontal] -Incorrect:: `dnf` is a package manager for Fedora. -Correct:: The `dnf` program is a package manager for Fedora. - -In headings, always capitalize the first word regardless of the type of speech. All subsequent words are also capitalized other than articles ("a," "an," or "the"), short prepositions ("in," "of," "for," "with," "at," "on"), or conjunctions ("and," "but," "or"). - -.Examples - -* Avoid Using Contractions in Technical Writing -* Try to Do the Right Thing -* Find the Right Way to Say What You Mean -* The Grass is Always Greener on the Other Side of the Fence - -=== Punctuation - -Punctuation is a crucial component of understanding prose. A misplaced comma, period, or an improper punctuation mark changes a sentence's meaning entirely. Punctuation marks are the fasteners in a writer's toolbox. Readers are accustomed to the regular nails and screws, like commas and periods. Start throwing in lots of flashy hinges or braces like semicolons or ellipses, and the unfamiliar notations easily distract readers. Complex punctuation marks are not universal, hindering translation efforts of Fedora Documentation. - -Minimize the following punctuation marks in documentation: - -[horizontal] -Parentheses or "em dashes.":: To compensate, rearrange the sentence, or break it into two complete thoughts. -Semicolons:: Good to use only if two thoughts are related, must be joined for clarity, and removes the need for a conjunction. -Colon:: If there are more than three items, use a bulleted list for easy comprehension. -Ellipsis:: Do not use for stylistic emphasis... only to denote an indefinite continuation of content in an example. -Exclamation points:: In technical writing this is accepted for use only as a most dire "warning" admonition, not for emphasis. -Ampersands:: The word "and" is to be written out, and this mark only reserved if it is part of a computer command. -Slashes:: Do not use slashes for a short hand version of "he or she" by using he/she, instead use the words "and," "or," or "either." Slashes are commonly used in file paths and using them otherwise will create confusion. diff --git a/en-US/style-guide/writing-guidelines.adoc b/en-US/style-guide/writing-guidelines.adoc deleted file mode 100644 index f35052c..0000000 --- a/en-US/style-guide/writing-guidelines.adoc +++ /dev/null @@ -1,79 +0,0 @@ -== General Writing Guidelines - -=== Be Bold, Concise, Clear, and Professional - -Be bold and direct. -Embellishments used in spoken language do not add value to a written technical document. -Use qualifiers like *usually*, *should*, and *often* sparingly. -Avoid narrative language such as "now that we have configured with the file, we are going to issue a command." - -Be concise. -Don't use unnecessary phrases and frivolous clauses. -Consider creating a separate section or referring to another document if elaboration is required. - -Be clear. -Explain one idea at a time, and avoid overwhelming the reader with too many details. -Be accurate and precise in your examples. -Your examples should adequately cover a stock installation of a current version of Fedora. - -Be professional. -Keep your writing relevant and impersonal. -Use clear, contextually appropriate language that will easily translate across languages and cultures. -Review your writing for spelling mistakes and grammar abuse. - -=== Use Active Voice - -Write instructions and rules using an _active voice_, presenting confidence to the reader without sounding demanding. -An active voice provides clear directions. -It shows the reader what to do and demonstrates expected results. -Active voice leaves the reader with the impression an author stands behind the written work. - -[WARNING] -.Avoid Passive Voice Unless Necessary -==== -Passive voice is completely correct from a grammatical standpoint, but it is a barrier to reading comprehension. -The passive voice flips conventional sentence structure around. -It moves the verb and direct object forward to the first half of a sentence, and places the main subject in the second half of a sentence. -Often a simple restructuring of the sentence makes it active. -Long passive sentences frequently take multiple reads before a reader grasps the full meaning. -==== - -.Example -[horizontal] -Active Voice:: Select a strong password to improve personal security. -Passive Voice:: Personal security improves by a strong password being selected. - -=== Write in Context - -Give the reader enough context to understand the material that you are presenting, without overwhelming them with unnecessary detail or history. -Adhere carefully to the subject matter of the current section and the overall document. -Avoid making the reader skip ahead to put current material in context. -Provide a link to related documentation if the reader may need it for clarification or further study. - -=== Emphasis - -Emphasis is most effective when used sparingly. -Use methods of emphasis such as boldface, or italics text to draw attention to a new term. -Use admonitions to set off notable material, such as warnings or notes. -You can also emphasize a particular point by varying sentence formation or word choice. - -=== Accuracy and Precision - -Accuracy and precision are key to any technical document. -Choose words after considering as many use cases as possible. -For example, "go to" is not as precise as "click," yet "click" may not be accurate for all interface interactions. -As a better choice, The term "select" is accurate in any usage case and sufficiently precise. - -Do not become too preoccupied in an attempt to cover all potential usage cases. -Covering rare side cases elongates a document beyond reason, and the reader loses focus. - -=== Tense - -Tense is the time in which language takes place. -There are three main tenses: past, present, and future. -Select an appropriate tense for the document and adhere to it. - -For Fedora documentation, use the present tense whenever possible. -Maintaining the same tense for each statement in a document is vital for clarity. -Keep the same tense for all sequential tasks in a procedure. -A short final sentence stays with the reader to the next section. diff --git a/en-US/tools.adoc b/en-US/tools.adoc deleted file mode 100644 index 72cba42..0000000 --- a/en-US/tools.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Tools - -The following tools are required to work with Fedora Documentation. - -== Writing -* git -* a text editor - -== Translations -* zanata-client - -== Publishing -* asciidoctor -* asciibinder diff --git a/en-US/writing-format.adoc b/en-US/writing-format.adoc deleted file mode 100644 index 5ca9b94..0000000 --- a/en-US/writing-format.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= Document Structure and Style - -== Structure - -In the past, Fedora used a book style format for documentation that was -intended to be read linearly. This style of documentation proved to be -cumbersome to both read and maintain. Most documentation is still -in book style format, however we are slowly migrating to topical -documentaiton sets. - -New documents should be written in a topical style so that each component -of the overall document set can be used on its own without needing to -read everything that was written in sections before it. An example of -this style of documentation can be found in the GNOME documentation at -https://help.gnome.org/users/gnome-help/stable/. - -Help is needed to convert our existing documentation to this new format. - -== Style - -FIXME need a style guide diff --git a/en-US/writing-markup.adoc b/en-US/writing-markup.adoc deleted file mode 100644 index f2b8402..0000000 --- a/en-US/writing-markup.adoc +++ /dev/null @@ -1,278 +0,0 @@ -= Document Markup - -== AsciiDoc - -Documentation is written using -http://www.methods.co.nz/asciidoc/index.html[AsciiDoc] as extended by -http://asciidoctor.org/[Asciidoctor]. - -== Formatting Guidelines - -When writing the following formatting rules apply to the AsciiDoc source -as used in Fedora: - -* Wrap paragraphs sensibly (~80 chars) to improve readability and diffs. - -* Format lists visually to make reading the source easy. - -* Headers are written in the single-line AsciiDoc format with equal - signs only on the left. - -* The title, which is the first line of the document, is the only level 1 - ( = ) title. Section headers within the topic must be level 2 ( == ) - or lower. - -* Section anchors must be all lowercase letters, with no line spaces - between the anchor and the section title. Anchors are typically the - same as their title with the spaces replaces by dashes. -+ ----- -[[section-anchor-name]] -=== Section Title ----- - -* In general, try to generalize documentation to eliminate the need to - reference Fedora or a specific version of Fedora. If this cannot - be avoided, use the entities below instead of actually writing out - the reference. This allows us to easily update version numbers and - names as needed. -+ -FIXME - add entities -+ -For example: -+ ----- -You can deploy applications on {product-title}. ----- - -* Links to other AsciiDoc files are always created with `link:`. Links to - external websites are created using the short format `url[text]`. -+ -FIXME - should we use xref for internal references -+ -For example: -+ ----- -You should fully understand link:other.adoc[foo, bar and baz] before attempting this procedure. -The repository of http://example.com[examples] contains many functional prototypes for you to extend. ----- -+ -Whenever possible the link to another topic should be part of the actual - sentence. Avoid creating links as a separate sentence that begins with - "See [this topic] for more information on x". - -* The following elements are marked up semantically as `[tag]#content#` - where tag is one of the following: - -** acronym - An often pronounceable word made from the initial (or - selected) letters of a name or phrase -** application - The name of a software program -** citetitle - The title of a cited work -** command - The name of an executable program or other software command -** filename - The name of a file -** literal - Inline text that is some literal value -** option - An option for a software command -** package - A name of a software package (e.g. a RPM) -** parameter - A value or a symbolic reference to a value -** replaceable - Content that may or must be replaced by the user -** systemitem - A system-related item or term - - -* The following elements are marked up semantically the same way as: - `[button]#content#` . These are all marked up using `button`. - -** guibutton -** guilabel -** guimenuitem -** guimenu -** guisubmenu -** keycap -** keycombo - -* Sharing content between files -+ -If you want to share content from one topic so that it appears in another topic, -you can use the `include` directive. See the Asciidoctor documentation for -details: -+ -http://asciidoctor.org/docs/user-manual/#include-partial -+ -If you find that you need to include content from one topic multiple times into -another topic, see the following usage: -+ -http://asciidoctor.org/docs/user-manual/#include-multiple - -* Images -If you want to link to an image: -* -1. Put it in `/images` -2. In the topic document, use this format to link to an image: -+ ----- -image::[image] ----- -+ -You only need to specify ``. The build mechanism automatically specifies the file path. - -* System blocks, table delimiters -+ -For all of the system blocks including table delimiters, use four characters. For example: -+ -.... -|=== for tables ----- for code blocks -.... - -* Code blocks -Code blocks are used to show examples of command screen outputs, or configuration files. When using command blocks always use the actual values for any items that a user would normally replace. Code blocks should represent exactly what a customer would see on their screen. If you need to expand or provide information on what some of the contents of a screen output or configuration file represent, then use callouts to provide that information. -+ -Follow these general guidelines when using code blocks: -+ -* Do NOT show replaceables within code blocks. -+ -* Do NOT use any markup in code blocks; code blocks generally do not accept any markup -+ -* Try to use callouts to provide information on what the output represents when required -+ -For all code blocks, you must include an empty line above a code block. -+ -Acceptable: -+ -.... -Lorem ipsum - ----- -$ lorem.sh ----- -.... -+ -Not acceptable: -+ -.... -Lorem ipsum ----- -$ lorem.sh ----- -.... -+ -Without the line spaces the content is likely to be not parsed correctly. - -* Inline Code or Commands -Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax. -+ -Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks: -+ -When writing an inline command example do not nest markup. For example, write `[command]#ls -l#` not `[command]#ls [option]#-l##` -+ -.... -Use the `GET` operation to do x. -.... -+ -This renders as: -+ -Use the `GET` operation to do x. - -** Command syntax and examples -The main distinction between showing command syntax and example is that a command syntax should just show customers how to use the command without real values. An example on the other hand should show the command with actual values with an example output of that command, where applicable. - -** Command syntax -To markup command syntax, use the code block and wrap the replaceables in <> with the required command parameters, as shown in the following example. Do NOT use commands or command syntax inline with sentences. -+ -.... -The following command returns a list of objects for the specified object type: - ----- -oc get ----- -.... -+ -This would render as follows: -+ -The following command returns a list of objects for the specified object type: -+ ----- -oc get ----- - -***Examples -As mentioned an example of a command should use actual values and also show an output of the command, as shown in the following example. In some a heading may not be required. -+ -.... -In the following example the `oc get` operation returns a complete list of services that are currently defined. - -.Example Title -==== - ----- -$ oc get se -NAME LABELS SELECTOR IP PORT -kubernetes component=apiserver,provider=kubernetes 172.30.17.96 443 -kubernetes-ro component=apiserver,provider=kubernetes 172.30.17.77 80 -docker-registry name=registrypod 172.30.17.158 5001 ----- -==== -.... -+ -This would render as shown: -+ -In the following example the `oc get` operation returns a complete list of services that are currently defined. -+ -.Example Title -==== - ----- -$ oc get se -NAME LABELS SELECTOR IP PORT -kubernetes component=apiserver,provider=kubernetes 172.30.17.96 443 -kubernetes-ro component=apiserver,provider=kubernetes 172.30.17.77 80 -docker-registry name=registrypod 172.30.17.158 5001 ----- -==== - - -*** Lists -Lists are created as shown in this example: -+ -.... -. Item 1 (2 spaces between the period and the first character) - -. Item 2 - -. Item 3 -.... -+ -This will render as such: - -. Item 1 - -. Item 2 - -. Item 3 -+ -If you need to add any text, admonitions, or code blocks you need to add the continuous +, as shown in the example: -+ -.... -. Item 1 -+ ----- -some code block ----- - -. Item 2 - -. Item 3 -.... -+ -This renders as shown: -+ -. Item 1 -+ ----- -some code block ----- - -. Item 2 - -. Item 3 - -FIXME - How to do NOTES, WARNINGS, AND ADMONITIONS diff --git a/index-main.html b/index-main.html deleted file mode 100644 index e3ae701..0000000 --- a/index-main.html +++ /dev/null @@ -1,138 +0,0 @@ - - - - - - - - - Fedora Documentation Website - - - - - - - - - - - -
-
-
- -
-
-
-
-

Fedora Documentation Guide Site

-

Test Build.

-
-
-
Fedora Documentation Guide
-
- -  Current Documentation - -
-
-
-
-
-
-
-
-
-

About

-
-
-
About Fedora
-
Sponsors
-
Fedora Magazine
-
Legal
-
-
    -
  • - -
    • -
  • - -
    • -
  • - -
    • -
-
-
- -
-

Download

-
-
-
Get Fedora Workstation
-
Get Fedora Server
-
Get Fedora Atomic
-
Fedora Spins
-
Fedora Labs
-
Fedora ARM®
-
Alternative Downloads
- -
-
-
- -
-

Support

-
-
-
Get Help
-
Ask Fedora
-
Common Bugs
-
Fedora Developer Portal
-
Installation Guide
-
-
-
- -
-

Join

-
-
-
Join Fedora
-
Planet Fedora
-
Fedora SIGs
-
Fedora Account System
-
Fedora Community
-
-
-
-
- -
-
-
- -
-
-
-
- - -

© 2017 Red Hat, Inc. and others. Please send any comments or corrections to the websites team

-
-
-
- -
-
-
- - - - - - diff --git a/modules/ROOT/assets/images/title_logo.svg b/modules/ROOT/assets/images/title_logo.svg new file mode 100644 index 0000000..e8fd52b --- /dev/null +++ b/modules/ROOT/assets/images/title_logo.svg @@ -0,0 +1,61 @@ + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..e348921 --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1,15 @@ +* xref:index.adoc[Contributing] +* xref:pr.adoc[Pull Requests] +* xref:publishing-translation.adoc[Publishing Translations] +* xref:repo-org.adoc[Organization] +* xref:tools.adoc[Tools] +* xref:writing-format.adoc[Documentation Format] +* xref:writing-markup.adoc[Documentation Markup] +* Name: Style Guide +** xref:style-guide/introduction.adoc[Introduction to the Style Guide] +** xref:style-guide/writing-guidelines.adoc[General Writing Guidelines] +** xref:style-guide/syntax-usage.adoc[Syntax and Language Usage] +** xref:style-guide/dates-times.adoc[Dates and Times] +** xref:style-guide/numbers.adoc[Numbers] +** xref:style-guide/abbreviation.adoc[Abbreviations] +** xref:style-guide/lists.adoc[Lists] diff --git a/modules/ROOT/pages/_partials/Feedback.adoc b/modules/ROOT/pages/_partials/Feedback.adoc new file mode 100644 index 0000000..d11787f --- /dev/null +++ b/modules/ROOT/pages/_partials/Feedback.adoc @@ -0,0 +1,26 @@ + +:experimental: + +=== We want feedback +indexterm:[feedback,contact information for this manual] +If you find errors or have suggestions for improvement, we want your advice. Submit a report in Bugzilla against the product `{PRODUCT}` and the component `{BOOKID}`. The following link automatically loads this information for you: {BZURL}. + +In Bugzilla: + +. Provide a short summary of the error or your suggestion in the `Summary` field. + +. Copy the following template into the `Description` field and give us the details of the error or suggestion as specifically as you can. If possible, include some surrounding text so we know where the error occurs or the suggestion fits. ++ +[subs="quotes"] +---- +Document URL: + +Section number and name: + +Error or suggestion: + +Additional information: + +---- + +. Click the btn:[Submit Bug] button. diff --git a/modules/ROOT/pages/_partials/Legal_Notice.adoc b/modules/ROOT/pages/_partials/Legal_Notice.adoc new file mode 100644 index 0000000..b65d4a5 --- /dev/null +++ b/modules/ROOT/pages/_partials/Legal_Notice.adoc @@ -0,0 +1,22 @@ + +:experimental: + +Copyright {YEAR} {HOLDER}. + +The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at link:++http://creativecommons.org/licenses/by-sa/3.0/++[]. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. + +Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. + +Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. + +For guidelines on the permitted uses of the Fedora trademarks, refer to link:++https://fedoraproject.org/wiki/Legal:Trademark_guidelines++[]. + +*Linux* (R) is the registered trademark of Linus Torvalds in the United States and other countries. + +*Java* (R) is a registered trademark of Oracle and/or its affiliates. + +*XFS* (R) is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. + +*MySQL* (R) is a registered trademark of MySQL AB in the United States, the European Union and other countries. + +All other trademarks are the property of their respective owners. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..234be01 --- /dev/null +++ b/modules/ROOT/pages/index.adoc @@ -0,0 +1,31 @@ += Contribute to Fedora documentation + +== Different ways to contribute + +There are a few different ways you can contribute to Fedora documentation. +While all of these are great ways to contribute, we've listed them in the order of maximum impact. + +* To do the work yourself, or if it is a substantial change, you should clone the repository, make your changes, and submit a pull request (PR). +Each PR should have closely-related changes. +In particular, it is a good idea to use separate PRs for bug-fix changes (for an old or current release) vs enhancement changes (for an upcoming new release). +Further information about link:pr.html[PRs is available]. + +* Create an issue in https://pagure.io/[pagure.io] in the repository of the appropriate document. +See the link:#repository-list[Fedora Docs repository list] below for more details. + +* Email the Fedora documentation team: docs@lists.fedoraproject.org. + + +[[repository-list]] +== Repository list + +Major documents or documentation sets are separated into separate repositories. +All repositories are stored in https://pagure.io/[pagure.io]. + +The major documents and documentations sets are: + +* Release Notes - https://pagure.io/fedora-docs/release-notes +* Installation Guide - https://pagure.io/fedora-docs/install-guide +* System Administrator's Guide - https://pagure.io/fedora-docs/system-administrators-guide + +This document is stored in https://pagure.io/fedora-docs/documentation-guide. diff --git a/modules/ROOT/pages/pr.adoc b/modules/ROOT/pages/pr.adoc new file mode 100644 index 0000000..474ad66 --- /dev/null +++ b/modules/ROOT/pages/pr.adoc @@ -0,0 +1,95 @@ += Understanding pull-request workflow + +Fedora documentation uses Git to store source files and facilitate collaboration. Using so-called pull requests is an established workflow for the Git version control system. This section provides basic guidelines for Git use and outlines a workflow to be followed when working with documentation repositories. + +== Guidelines + +Learn about basic best practices to make collaboration streamlined. + +=== Keep writing + +Provide a clear statement of the changes that are included in the _pull request_ (PR). +This will help the right people see your changes and will aid in getting them reviewed faster. + +=== Keep it small + +Giant dumps or edits make reviews a lengthy and time consuming process. +For the sake of the review and yourself, keep PRs as small as you can while still making sense. + +To provide a large number of edits to existing documents, group them by section, or by the type of correction you are making. +If you are adding new content keep limit each PR to a new page or section. + +However, each PR must be fully self-contained. +The balance you want to strike is between readability and manageability of the PR; ensuring that each PR, when committed, leaves the documentation logical and complete. + +=== Keep it clean + +Histories are an extremely valuable part of using a version control system, but providing a history of your small changes may not be as useful. +If you are the type of person who commits often locally, and you tend to have lots of commits making up your PRs, look at using `git{nbsp}rebase` to combine commits into a smaller number of more verbose commits. + +=== Keep paying attention + +As the PR submitter, your job is not done once you start the process. +Make sure to stay engaged and work with the people reviewing your changes. + +=== Keep a good attitude + +After putting a lot of work into something, it is natural to take reviews as a personal attack. +Try and remember that this process is designed to help create the best possible end-product for Fedora. +It is important to keep that in mind and not to let it discourage you from continuing. + +=== Keep it legal + +FIXME: If you're referencing a third-party repo or other proprietary software, please include the third-party legal admonition at the top of the page. + +== Workflow + +The sources for Fedora's documentation are stored in Git repositories at link:https://pagure.io[pagure.io]. +Contributions are accepted via _pull requests_, which merge changes from your copy of the repository into the original. + +. Install the required link:tools.html[tools]. + +. Log into Pagure and click the *Fork* button in the upper right-hand corner of a repository. +You now have a personal copy of the repo, called a _fork_. + +. Clone your fork of the repository using the *SSH* URL. ++ +.... +$ git clone ssh://git@pagure.io/forks//documentation-guide.git +$ cd documentation-guide +.... + +. Create a branch to contain your work. +This makes it easier for others to pull from your repo without disrupting their existing content. +You can name the branch anything, but something that correlates to the work you'll be doing is best. ++ +.... +$ git checkout -b pull_request_workflow +.... + +. Make your changes using the editor of your choice. Add a commit for each distinct change. ++ +.... +$ git add en-US/pr.adoc +$ git commit -m 'begin describing pull request workflow' +.... + +. #FIXME# - how to build previews + +. Push your changes to Pagure. ++ +.... +$ git push origin +.... + +. #FIXME# - add how to keep your branch up to date with other changes while working and how to do a final rebase to avoid merge conflicts (by adding a `git remote`). + +. #FIXME# - add how to squash commits. + +. The new branch will now appear in your fork on pagure. +Once you have pushed a cohesive set of changes, press the *New PR* button to start a new pull request. +Pagure will send your changes for review after you fill out the form and press *Create*. + +. Work with your reviewer to address any concerns. Subsequent commits pushed to this branch of your fork will be automatically included in the pull request. + +. Your changes get merged by the reviewer. Congratulations! Reward yourself with your favorite treat, you've earned it! Soon you'll also earn a link:https://badges.fedoraproject.org/[Fedora Badge]. diff --git a/modules/ROOT/pages/publishing-translation.adoc b/modules/ROOT/pages/publishing-translation.adoc new file mode 100644 index 0000000..7026eee --- /dev/null +++ b/modules/ROOT/pages/publishing-translation.adoc @@ -0,0 +1,3 @@ += Publishing + +FIXME - Document final publishing tool and translation hand-off diff --git a/modules/ROOT/pages/repo-org.adoc b/modules/ROOT/pages/repo-org.adoc new file mode 100644 index 0000000..fd7a9a8 --- /dev/null +++ b/modules/ROOT/pages/repo-org.adoc @@ -0,0 +1,12 @@ +[[repository-organization]] +== Repository Organization + +Major documents and/or documentation sets are separated +into separate repositories. All repositories are stored in +https://pagure.io/[pagure.io]. + +FIXME document repository structure + +* Files in every repo +* branches are versions +* master latest "rawhide" documentation diff --git a/modules/ROOT/pages/style-guide/abbreviations.adoc b/modules/ROOT/pages/style-guide/abbreviations.adoc new file mode 100644 index 0000000..5c7cec2 --- /dev/null +++ b/modules/ROOT/pages/style-guide/abbreviations.adoc @@ -0,0 +1,54 @@ +== Abbreviations + +=== The United States + +As a noun appearing alone, use `United States`. + +---- +...the government of the United States... +---- + +As a noun appearing as part of a locality, use `US` with no periods and no spaces. + +---- +Raleigh, NC, US +US, Earth +---- + +As an adjective, use `U.S.` with no spaces. + +---- +...the U.S. government... +---- + +==== States + +Spell out state names when they appear alone. + +---- +...the government of North Carolina... +---- + +When abbreviating state names, use their two-letter ZIP standard abbreviations. + +Abbreviate state names when they appear as part of a locality. + +---- +Raleigh, NC +---- + +Place one comma between the city and state name and another after the state name, unless it ends the sentence or is part of a dateline. + +---- +...founded in Raleigh, NC, by Red Hat... +...managed from Raleigh, NC. +---- + +=== Academic Degrees + +* Avoid abbreviating degrees. +* Use an apostrophe in bachelor's degree, master's, etc. +* Do not use an apostrophe in Bachelor of Arts, Master of Science, etc. +* Use abbreviations only when the preferred method would be cumbersome. +* Use abbreviations only after a full name. +* Set abbreviations apart with commas. diff --git a/modules/ROOT/pages/style-guide/dates-times.adoc b/modules/ROOT/pages/style-guide/dates-times.adoc new file mode 100644 index 0000000..af9409c --- /dev/null +++ b/modules/ROOT/pages/style-guide/dates-times.adoc @@ -0,0 +1,63 @@ +== Dates and Times + +The styles used for dates and times vary widely around the world, and this creates a lot of confusion. +While there is consensus on one calendar for most business purposes, the dates on this calendar can be represented in many different ways. +The varying uses of daylight saving time and assorted ways of representing time can make even simple communications more difficult. +International standards have been developed to effectively communicate dates and times, and these standards should be used for publications that may reach a global audience. + +Absolute dates and times specify specific points in time and may include points in the past, present, or future. + +The ISO 8601 standard provides a simple way to represent dates and times that is easily recognized around the world and is equally easy to use. +Under this standard, all values are ordered from most to least significant. +Write all absolute dates and times in accordance with the ISO 8601 standard. + +=== Dates + +Use the following guidelines when writing general dates: + +* Spell out days of the week and separate them from dates using a comma. +* When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD) to avoid confusion. +* When listing a day and month: +** List the day first. +** Spell out the day. +** Set the day and month apart with `of`. +** Spell out the month. +* When listing a month and year: +** List the month first. +** Spell out the month. +** Set the month and year apart with `of`. +** Use Arabic numerals for the year. + +.Examples +---- +Sunday, 2000-01-01 +2000-01-01 +The first of January +January of 2000 +---- + +=== Times + +Use the following guidelines when writing general times: + +* Use 24-hour time formats. +* Always use units. +* Follow absolute times with a timezone specification. +* Separate days, hours, minutes and seconds with a colon and no spaces. +* Separate seconds and fractions thereof with periods. +* If the scope of a specification is unclear, increase the precision or specify the scope of the lowest precision. +* Use Coordinated Universal Time (UTC) for all worldwide events. +The Coordinated Universal Time (UTC) is a universally recognized time standard and is preferred for time specifications. +This is sometimes referred to as Greenwich Mean Time (GMT) or Zulu Time (Z). +The preferred way to specify a time in UTC is to follow the time with a space and `UTC`. +* Localized events may be specified using UTC or the local time, but always specify a timezone or offset. + +.Examples +---- +15:00 UTC +1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second) +15:00 minutes (15 minutes) +15:30 hours (15 hours and 30 minutes) +The global conference will take place at 15:00 UTC. +The event will be in Raleigh, NC, and will take place at 11:00 UTC-4. +---- diff --git a/modules/ROOT/pages/style-guide/introduction.adoc b/modules/ROOT/pages/style-guide/introduction.adoc new file mode 100644 index 0000000..d94980a --- /dev/null +++ b/modules/ROOT/pages/style-guide/introduction.adoc @@ -0,0 +1,10 @@ +== Introduction to the Style Guide + +Writing high-quality documention is a challenge. +In order to provide consistent, readable documentation, Fedora provides this style guide as a standard. +The style guide aims to increase readability and comprehension for users and developers of Fedora, who come from a wide variety of backgrounds and experiences. + +This style guide may vary from each contributor's familiar writing style. +The Fedora Documentation Style Guide borrows many ideas from the Associated Press (AP) Stylebook and The Chicago Manual of Style. +Any differences from those guides are intended to enhance the value of documents for international readers, and accommodate the technical nature of Fedora documentation. +Particular care is made to adopt international standards for common notations to avoid confusion across cultural lines. diff --git a/modules/ROOT/pages/style-guide/lists.adoc b/modules/ROOT/pages/style-guide/lists.adoc new file mode 100644 index 0000000..de796d6 --- /dev/null +++ b/modules/ROOT/pages/style-guide/lists.adoc @@ -0,0 +1,9 @@ +== Lists +Capitalize and use periods when the list items are complete sentences. +Make them agree so that there aren't a mixture of sentences and fragments. + +You could also have a list with a colon: + +* that was lowercase and not punctuated +* that again doesn't mix forms +* that is likely very short diff --git a/modules/ROOT/pages/style-guide/numbers.adoc b/modules/ROOT/pages/style-guide/numbers.adoc new file mode 100644 index 0000000..5c7d876 --- /dev/null +++ b/modules/ROOT/pages/style-guide/numbers.adoc @@ -0,0 +1,50 @@ +== Numbers + +=== When to Spell Out a Number + +Rules for using Arabic numerals or spelling out numbers are as follows and are listed from highest priority to lowest. + +* If the number is part of a casual expression, spell it out. +* If the number is a calendar year, do not spell it out. +* If the number is an age or percentage, do not spell it out. +* If the number begins a sentence, spell it out. +Awkward sentences should be reformed. +* If the number is greater than 10, do not spell it out. +* If the number is one through nine, spell it out. + +.Examples +---- +Five horses ran in the field. +Fedora 27 was released in 2017. +I cannot eat 27 slices of pizza. +I built eight packages for Fedora. +---- + +=== When to Use Roman Numerals + +Use Roman numerals for wars and honorific suffixes. + +.Examples +---- +World War II +John Doe III +---- + +=== Cardinal Numbers and Ordinal Numbers + +Cardinal numbers include figures 1, 2, 10, 101, and so on, and the corresponding words. + +Ordinal numbers include the terms 1st, 2nd, 10th, 101st, and so on, and the corresponding words. + +=== Large Numbers + +When spelling out large numbers, connect words ending in 'y' to subsequent words within the same number with a hyphen. +Avoid commas between words that are part of one number. + +.Examples +---- +twenty-one +one hundred thirty-one +twenty-five thousand one hundred thirty-one +ninety bottles +---- diff --git a/modules/ROOT/pages/style-guide/syntax-usage.adoc b/modules/ROOT/pages/style-guide/syntax-usage.adoc new file mode 100644 index 0000000..f4916e7 --- /dev/null +++ b/modules/ROOT/pages/style-guide/syntax-usage.adoc @@ -0,0 +1,132 @@ +== Syntax and Language Usage + +=== Contractions + +Avoid contractions, the combination of two words with an apostrophe replacing one or more letters. +Contractions reduce the readability of documents and make translation more difficult. +Other cultures and languages interpret contractions differently, and this confusion conflicts with the goals of the Fedora documentation. + +=== Pronouns + +Pronouns are words that languages use to replace specific noun phrases. +Good writers must strike a balance between over-repeating a noun phrase, and using pronouns to stand in for nouns. +A general rule to preserve clarity is to never repeat noun substitution with a pronoun in two consecutive sentences. +Readers of technical documents need constant reminders on the exact subject the author is referring to. +The over-use of pronouns causes readers to make a guess about the subject a sentence. +These assumptions reduce the effectiveness of documentation. + +Avoid most personal pronouns in documentation, including the following: + +* Subjective personal pronouns ("I," "he," "she," "it," "we,") +* Objective personal pronouns ("me," "her," "him," "us") +* Possessive personal pronouns ("my," "her," "his," "our") + +Also avoid: + +* Reflexive pronouns, such as "yourself" or "himself" +* Intensive pronouns, such as "he himself" or "(you) do it yourself" +* Resist overuse of "you", "your", and "one/one's" + +Occasionally situations require the second personal pronoun "you," and its attendant forms for clarity. +Maintaining an active voice is paramount over avoiding the second personal pronouns. +"You" and "your" are appropriate words to indicate action or possession on the part of the reader. + +Indefinite pronouns such as "this" or "that" without an antecedent make it tough for a reader to follow an author's meaning. +Favor writing an exact noun phrase whenever possible over the vague words "this," "these," "those," and "that." + +.Example +[horizontal] +Incorrect:: Edit your DNF configuration files to use geographically close mirrors. +This allows you to update your system faster. +Correct:: Edit the DNF configuration files to use geographically close mirrors for faster system updates. + +When eliminating indefinite pronouns, a long sentence may result from joining too many clauses. +Use indefinite pronouns to break long sentences up to improve clarity, but always provide a proper antecedent. + +.Example +[horizontal] +Incorrect:: Stay current with recommended updates to your operating system in order to improve functionality of applications, remove security risks, and automatically resolve performance issues solved from bug reports. +Correct:: Stay current with recommended updates to your operating system. +These updates improve functionality of applications, remove security risks, and automatically resolve performance issues solved from bug reports. + +=== Sentence Formation + +Keep sentences as short as possible. +Cutting unnecessary words is vital to strengthen meaning. +There are a number of common traps technical writers fall into resulting in lengthy sentences. + +==== Indirect Discourse + +Indirect discourse refers to the use of "that" to attribute a statement, fact, or feeling in a sentence without the use of quotation marks. +In regular writing, it weakens statements of fact. +Documentation writers can improve the impact of sentences by removing "that" and "which". + +.Example +[horizontal] +Incorrect:: Fedora is an operating system that is upstream for many other open source projects. +Correct:: Fedora is an upstream operating system for many other open source projects. + + +==== Other Unnecessary Word Combinations + +Avoid using the unnecessary word "then" following an "if" statement. +When a sentence begins with an "if" statement, follow it with a comma and complete the sentence with a full statement. + +.Example +[horizontal] +Incorrect:: If an email client will not send or receive messages, then check under the File Menu and verify "Work Offline" mode is unselected. +Correct:: If an email client will not send or receive messages, check under the File Menu and +verify "Work Offline" mode is unselected. + +Many words we use in everyday conversation reduce impact in printed materials because they "leave a way out." These are words preceding verbs and nouns to minimize the sentence's influence. +This is not an exhaustive list, but mindful documentation writers will reduce using these words and those of a similar nature. + +[WARNING] +.Avoid Reducing Impact With Unnecessary Words +==== +The following words minimize the impact of the verb or noun clause within a sentence. +Other words also fit into this category, but this short list is aimed at helping documentation writers identify words of this nature and eliminate them from their writing: *should, could, may, might, perhaps, some, many, most, numerous, few, somewhat, whatever, possibly, can, occasionally,* and *frequently*. +==== + + +==== Sentence Variation + +For the strongest impact, keep the first and last sentences of a paragraph as short as possible. +Varying sentence length within a paragraph and through the entire document keeps a reader's attention. +A short and simple fact is easy to grasp. +There is nothing wrong with using longer sentences to explain complex ideas and concepts, and long as they are still clear. +Try to use a simple synopsis sentence at the end of each paragraph to give readers a reprieve and recap of any important information. +A short final sentence stays with the reader to the next section. + +=== Capitalization + +In sentences, capitalize the first word. Do not start sentences with a command, package, or option name. + +.Example +[horizontal] +Incorrect:: `dnf` is a package manager for Fedora. +Correct:: The `dnf` program is a package manager for Fedora. + +In headings, always capitalize the first word regardless of the type of speech. All subsequent words are also capitalized other than articles ("a," "an," or "the"), short prepositions ("in," "of," "for," "with," "at," "on"), or conjunctions ("and," "but," "or"). + +.Examples + +* Avoid Using Contractions in Technical Writing +* Try to Do the Right Thing +* Find the Right Way to Say What You Mean +* The Grass is Always Greener on the Other Side of the Fence + +=== Punctuation + +Punctuation is a crucial component of understanding prose. A misplaced comma, period, or an improper punctuation mark changes a sentence's meaning entirely. Punctuation marks are the fasteners in a writer's toolbox. Readers are accustomed to the regular nails and screws, like commas and periods. Start throwing in lots of flashy hinges or braces like semicolons or ellipses, and the unfamiliar notations easily distract readers. Complex punctuation marks are not universal, hindering translation efforts of Fedora Documentation. + +Minimize the following punctuation marks in documentation: + +[horizontal] +Parentheses or "em dashes.":: To compensate, rearrange the sentence, or break it into two complete thoughts. +Semicolons:: Good to use only if two thoughts are related, must be joined for clarity, and removes the need for a conjunction. +Colon:: If there are more than three items, use a bulleted list for easy comprehension. +Ellipsis:: Do not use for stylistic emphasis... only to denote an indefinite continuation of content in an example. +Exclamation points:: In technical writing this is accepted for use only as a most dire "warning" admonition, not for emphasis. +Ampersands:: The word "and" is to be written out, and this mark only reserved if it is part of a computer command. +Slashes:: Do not use slashes for a short hand version of "he or she" by using he/she, instead use the words "and," "or," or "either." Slashes are commonly used in file paths and using them otherwise will create confusion. diff --git a/modules/ROOT/pages/style-guide/writing-guidelines.adoc b/modules/ROOT/pages/style-guide/writing-guidelines.adoc new file mode 100644 index 0000000..f35052c --- /dev/null +++ b/modules/ROOT/pages/style-guide/writing-guidelines.adoc @@ -0,0 +1,79 @@ +== General Writing Guidelines + +=== Be Bold, Concise, Clear, and Professional + +Be bold and direct. +Embellishments used in spoken language do not add value to a written technical document. +Use qualifiers like *usually*, *should*, and *often* sparingly. +Avoid narrative language such as "now that we have configured with the file, we are going to issue a command." + +Be concise. +Don't use unnecessary phrases and frivolous clauses. +Consider creating a separate section or referring to another document if elaboration is required. + +Be clear. +Explain one idea at a time, and avoid overwhelming the reader with too many details. +Be accurate and precise in your examples. +Your examples should adequately cover a stock installation of a current version of Fedora. + +Be professional. +Keep your writing relevant and impersonal. +Use clear, contextually appropriate language that will easily translate across languages and cultures. +Review your writing for spelling mistakes and grammar abuse. + +=== Use Active Voice + +Write instructions and rules using an _active voice_, presenting confidence to the reader without sounding demanding. +An active voice provides clear directions. +It shows the reader what to do and demonstrates expected results. +Active voice leaves the reader with the impression an author stands behind the written work. + +[WARNING] +.Avoid Passive Voice Unless Necessary +==== +Passive voice is completely correct from a grammatical standpoint, but it is a barrier to reading comprehension. +The passive voice flips conventional sentence structure around. +It moves the verb and direct object forward to the first half of a sentence, and places the main subject in the second half of a sentence. +Often a simple restructuring of the sentence makes it active. +Long passive sentences frequently take multiple reads before a reader grasps the full meaning. +==== + +.Example +[horizontal] +Active Voice:: Select a strong password to improve personal security. +Passive Voice:: Personal security improves by a strong password being selected. + +=== Write in Context + +Give the reader enough context to understand the material that you are presenting, without overwhelming them with unnecessary detail or history. +Adhere carefully to the subject matter of the current section and the overall document. +Avoid making the reader skip ahead to put current material in context. +Provide a link to related documentation if the reader may need it for clarification or further study. + +=== Emphasis + +Emphasis is most effective when used sparingly. +Use methods of emphasis such as boldface, or italics text to draw attention to a new term. +Use admonitions to set off notable material, such as warnings or notes. +You can also emphasize a particular point by varying sentence formation or word choice. + +=== Accuracy and Precision + +Accuracy and precision are key to any technical document. +Choose words after considering as many use cases as possible. +For example, "go to" is not as precise as "click," yet "click" may not be accurate for all interface interactions. +As a better choice, The term "select" is accurate in any usage case and sufficiently precise. + +Do not become too preoccupied in an attempt to cover all potential usage cases. +Covering rare side cases elongates a document beyond reason, and the reader loses focus. + +=== Tense + +Tense is the time in which language takes place. +There are three main tenses: past, present, and future. +Select an appropriate tense for the document and adhere to it. + +For Fedora documentation, use the present tense whenever possible. +Maintaining the same tense for each statement in a document is vital for clarity. +Keep the same tense for all sequential tasks in a procedure. +A short final sentence stays with the reader to the next section. diff --git a/modules/ROOT/pages/tools.adoc b/modules/ROOT/pages/tools.adoc new file mode 100644 index 0000000..72cba42 --- /dev/null +++ b/modules/ROOT/pages/tools.adoc @@ -0,0 +1,14 @@ += Tools + +The following tools are required to work with Fedora Documentation. + +== Writing +* git +* a text editor + +== Translations +* zanata-client + +== Publishing +* asciidoctor +* asciibinder diff --git a/modules/ROOT/pages/writing-format.adoc b/modules/ROOT/pages/writing-format.adoc new file mode 100644 index 0000000..5ca9b94 --- /dev/null +++ b/modules/ROOT/pages/writing-format.adoc @@ -0,0 +1,21 @@ += Document Structure and Style + +== Structure + +In the past, Fedora used a book style format for documentation that was +intended to be read linearly. This style of documentation proved to be +cumbersome to both read and maintain. Most documentation is still +in book style format, however we are slowly migrating to topical +documentaiton sets. + +New documents should be written in a topical style so that each component +of the overall document set can be used on its own without needing to +read everything that was written in sections before it. An example of +this style of documentation can be found in the GNOME documentation at +https://help.gnome.org/users/gnome-help/stable/. + +Help is needed to convert our existing documentation to this new format. + +== Style + +FIXME need a style guide diff --git a/modules/ROOT/pages/writing-markup.adoc b/modules/ROOT/pages/writing-markup.adoc new file mode 100644 index 0000000..f2b8402 --- /dev/null +++ b/modules/ROOT/pages/writing-markup.adoc @@ -0,0 +1,278 @@ += Document Markup + +== AsciiDoc + +Documentation is written using +http://www.methods.co.nz/asciidoc/index.html[AsciiDoc] as extended by +http://asciidoctor.org/[Asciidoctor]. + +== Formatting Guidelines + +When writing the following formatting rules apply to the AsciiDoc source +as used in Fedora: + +* Wrap paragraphs sensibly (~80 chars) to improve readability and diffs. + +* Format lists visually to make reading the source easy. + +* Headers are written in the single-line AsciiDoc format with equal + signs only on the left. + +* The title, which is the first line of the document, is the only level 1 + ( = ) title. Section headers within the topic must be level 2 ( == ) + or lower. + +* Section anchors must be all lowercase letters, with no line spaces + between the anchor and the section title. Anchors are typically the + same as their title with the spaces replaces by dashes. ++ +---- +[[section-anchor-name]] +=== Section Title +---- + +* In general, try to generalize documentation to eliminate the need to + reference Fedora or a specific version of Fedora. If this cannot + be avoided, use the entities below instead of actually writing out + the reference. This allows us to easily update version numbers and + names as needed. ++ +FIXME - add entities ++ +For example: ++ +---- +You can deploy applications on {product-title}. +---- + +* Links to other AsciiDoc files are always created with `link:`. Links to + external websites are created using the short format `url[text]`. ++ +FIXME - should we use xref for internal references ++ +For example: ++ +---- +You should fully understand link:other.adoc[foo, bar and baz] before attempting this procedure. +The repository of http://example.com[examples] contains many functional prototypes for you to extend. +---- ++ +Whenever possible the link to another topic should be part of the actual + sentence. Avoid creating links as a separate sentence that begins with + "See [this topic] for more information on x". + +* The following elements are marked up semantically as `[tag]#content#` + where tag is one of the following: + +** acronym - An often pronounceable word made from the initial (or + selected) letters of a name or phrase +** application - The name of a software program +** citetitle - The title of a cited work +** command - The name of an executable program or other software command +** filename - The name of a file +** literal - Inline text that is some literal value +** option - An option for a software command +** package - A name of a software package (e.g. a RPM) +** parameter - A value or a symbolic reference to a value +** replaceable - Content that may or must be replaced by the user +** systemitem - A system-related item or term + + +* The following elements are marked up semantically the same way as: + `[button]#content#` . These are all marked up using `button`. + +** guibutton +** guilabel +** guimenuitem +** guimenu +** guisubmenu +** keycap +** keycombo + +* Sharing content between files ++ +If you want to share content from one topic so that it appears in another topic, +you can use the `include` directive. See the Asciidoctor documentation for +details: ++ +http://asciidoctor.org/docs/user-manual/#include-partial ++ +If you find that you need to include content from one topic multiple times into +another topic, see the following usage: ++ +http://asciidoctor.org/docs/user-manual/#include-multiple + +* Images +If you want to link to an image: +* +1. Put it in `/images` +2. In the topic document, use this format to link to an image: ++ +---- +image::[image] +---- ++ +You only need to specify ``. The build mechanism automatically specifies the file path. + +* System blocks, table delimiters ++ +For all of the system blocks including table delimiters, use four characters. For example: ++ +.... +|=== for tables +---- for code blocks +.... + +* Code blocks +Code blocks are used to show examples of command screen outputs, or configuration files. When using command blocks always use the actual values for any items that a user would normally replace. Code blocks should represent exactly what a customer would see on their screen. If you need to expand or provide information on what some of the contents of a screen output or configuration file represent, then use callouts to provide that information. ++ +Follow these general guidelines when using code blocks: ++ +* Do NOT show replaceables within code blocks. ++ +* Do NOT use any markup in code blocks; code blocks generally do not accept any markup ++ +* Try to use callouts to provide information on what the output represents when required ++ +For all code blocks, you must include an empty line above a code block. ++ +Acceptable: ++ +.... +Lorem ipsum + +---- +$ lorem.sh +---- +.... ++ +Not acceptable: ++ +.... +Lorem ipsum +---- +$ lorem.sh +---- +.... ++ +Without the line spaces the content is likely to be not parsed correctly. + +* Inline Code or Commands +Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax. ++ +Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks: ++ +When writing an inline command example do not nest markup. For example, write `[command]#ls -l#` not `[command]#ls [option]#-l##` ++ +.... +Use the `GET` operation to do x. +.... ++ +This renders as: ++ +Use the `GET` operation to do x. + +** Command syntax and examples +The main distinction between showing command syntax and example is that a command syntax should just show customers how to use the command without real values. An example on the other hand should show the command with actual values with an example output of that command, where applicable. + +** Command syntax +To markup command syntax, use the code block and wrap the replaceables in <> with the required command parameters, as shown in the following example. Do NOT use commands or command syntax inline with sentences. ++ +.... +The following command returns a list of objects for the specified object type: + +---- +oc get +---- +.... ++ +This would render as follows: ++ +The following command returns a list of objects for the specified object type: ++ +---- +oc get +---- + +***Examples +As mentioned an example of a command should use actual values and also show an output of the command, as shown in the following example. In some a heading may not be required. ++ +.... +In the following example the `oc get` operation returns a complete list of services that are currently defined. + +.Example Title +==== + +---- +$ oc get se +NAME LABELS SELECTOR IP PORT +kubernetes component=apiserver,provider=kubernetes 172.30.17.96 443 +kubernetes-ro component=apiserver,provider=kubernetes 172.30.17.77 80 +docker-registry name=registrypod 172.30.17.158 5001 +---- +==== +.... ++ +This would render as shown: ++ +In the following example the `oc get` operation returns a complete list of services that are currently defined. ++ +.Example Title +==== + +---- +$ oc get se +NAME LABELS SELECTOR IP PORT +kubernetes component=apiserver,provider=kubernetes 172.30.17.96 443 +kubernetes-ro component=apiserver,provider=kubernetes 172.30.17.77 80 +docker-registry name=registrypod 172.30.17.158 5001 +---- +==== + + +*** Lists +Lists are created as shown in this example: ++ +.... +. Item 1 (2 spaces between the period and the first character) + +. Item 2 + +. Item 3 +.... ++ +This will render as such: + +. Item 1 + +. Item 2 + +. Item 3 ++ +If you need to add any text, admonitions, or code blocks you need to add the continuous +, as shown in the example: ++ +.... +. Item 1 ++ +---- +some code block +---- + +. Item 2 + +. Item 3 +.... ++ +This renders as shown: ++ +. Item 1 ++ +---- +some code block +---- + +. Item 2 + +. Item 3 + +FIXME - How to do NOTES, WARNINGS, AND ADMONITIONS diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..acab783 --- /dev/null +++ b/preview.sh @@ -0,0 +1,18 @@ +#!/bin/sh + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "The preview will be available at http://localhost:8080/" + docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Let's assume that it's running the Docker deamon + # which requires root. + echo "" + echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it." + echo "The preview will be available at http://localhost:8080/" + sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx +fi diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..b41c5d7 --- /dev/null +++ b/site.yml @@ -0,0 +1,20 @@ +site: + title: Local Preview - Documentation Guide + start_page: documentation-guide::index +content: + sources: + - url: . + branches: HEAD +ui: + bundle: + url: https://asamalik.fedorapeople.org/ui-bundle.zip + snapshot: true + default_layout: with_menu +output: + clean: true + dir: ./public + destinations: + - provider: archive +runtime: + pull: true + cache_dir: ./cache