commit-squash

modules/ROOT/pages/contributing-docs/tools-edit-local-clone.adoc

@@ -3,28 +3,34 @@
 :page-pagination:
 Jocelyn G and Eli R
 
-This guide will show you how to set up a documentation (docs) editing environment with a local clone.
+This guide will show you how to set up a local documentation editing environment on your computer, using a local clone.
 
-[EXPLANATION]
-====
+****
 Editing locally allows you to make complex edits to multiple pages simultaneously.
-It also allows you to preview edits, exactly as they will appear once published on the  main docs site.
-====
+It also allows you to preview edits exactly as they will appear once published on the main docs site.
+****
 
 IMPORTANT: This guide deals only with repositories (repos) hosted on Fedora Forge.
-The process will differ for repos hosted on Gitlab, Github or Pagure.
+The process will differ for repos hosted on GitLab, GitHub, or Pagure.
 You can find the legacy guides for the previously used hosting platforms in the _contribution tools_ section of this website.
 
-For explanation and references on the Fedora docs tooling, please visit the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/[Contribute to Fedora docs] page.
+For explanations and references on the Fedora Docs tooling, please visit the xref:contributing-docs/index.adoc  [Contribute to Fedora docs] page.
 
-//above links to the live page not the draft of the updated one
+//above links to the current live page not the update draft.
 
 == Prerequisites
 
-* https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/#_prerequisites[*First steps*] section completed.
+* xref:contributing-docs/index.adoc#_prerequisites[*Prerequisites for Contributing to Docs*] section completed.
 * *Git* installed.
++
+In Fedora Linux, you can check that _git_ is installed by running the following command:
++
+----
+$ dnf install git
+----
 * *Text editor* of choice installed.
-It is beneficial but not essential if your text editor has integrated file navigation, terminal, and AsciiDoc syntax support.
++
+It is beneficial, but not essential, if your text editor has integrated file navigation, a terminal, and AsciiDoc syntax support.
 
 == Set up a local editing environment
 
@@ -39,11 +45,16 @@ cd    ~/fedora-docs
 
 
 2. Use the Forge web interface to fork the repo you intend to edit.
+Click the Fork button on the top-right corner of the project page:
++
+image::fork-button.png[]
++
+If prompted, enter the details to create your new fork. The default values are suitable in most cases.
 
-2. Configure your Forge access token and clone your remote fork to your machine.
-Follow the https://docs.fedoraproject.org/en-US/forge-documentation/using_http_auth/[How to clone a Forge repo using the HTTPS] guide to complete this.
+3. Configure your Forge access token and clone your remote fork to your computer.
+Follow the xref:forge-documentation::using_http_auth.adoc[How to clone a Forge repo using the HTTPS] guide to complete this.
 
-3. Configure the upstream repo in your local clone.
+4. Configure the upstream repo in your local clone.
 You will need this to fetch updates from the upstream main docs repo.
 +
 ----
@@ -58,7 +69,7 @@ git remote -v
 +
 The exact URLs may differ.
 But check that you have two origin entries that match your fork, and two upstream entries that match the upstream main docs repo URL.
-The return should resemble this:
+The output should resemble this:
 +
 ----
 origin  https://forge.fedoraproject.org/<forge-user-name>/<reponame>.git (fetch)
@@ -68,7 +79,7 @@ upstream        https://forge.fedoraproject.org/docs/<reponame>.git (push)
 ----
 +
 NOTE: The terms _origin_ and _upstream_ are not strict descriptors but commonly used names to refer to your fork and the upstream fork respectively.
-So you can indeed choose different names to represent the two different repos if you choose to.
+So you can choose different names to represent the two repos if you wish.
 
 5. Create a working branch:
 +
@@ -78,39 +89,53 @@ git checkout -b <branch-name-you-choose>
 
 //See here for an explanation of branches and why it is best practice to create a working branch/s.
 
-
-If making large changes, consider making  a new branch for each page, so the reviews can happen in stages. The benefit of this is that your changes remain separate from the main branch until they are merged into the main branch.
+****
+At its most basic level, branching is simply taking a snapshot of the main line of the repo and making changes to that branch.
+This keeps what you're working on separate from what others are working on and allows for multiple changes to be merged into the main branch.
+After you have made your changes to the files and committed those changes to your origin repo, you can then open a pull request to have your changes merged into the main branch and published on the docs site.
+****
 
 You are now ready to start writing.
 
-Consider making use of the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/[Fedora style guide] as well as the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-vale-linter/[Vale] tool to assist your editing.
+Consider making use of the xref:contributing-docs/style-guide.adoc[Fedora style guide] as well as the xref:contributing-docs/tools-vale-linter.adoc[Vale] tool to assist your editing.
 
 
 == Edit the AsciiDoc code with a text editor
 
-Configure your text editor or IDE of choice with the following three viewing windows:
+You can open and edit AsciiDoc files with any text editor.
+
+
+****
+Some text editors will provide three panes by default, and some will not show more than just the contents of the file that you are currently working on.
+Many graphical editors provide at least the folder structure and the .adoc file contents view at the same time; terminal editors will usually only show the contents of the .adoc file and may require either a second terminal window open or exiting the editor in order to run commands.
+****
+
+As an example configuration, you can use your text editor or IDE of choice with the following three viewing panes:
 
 * project folder structure.
 * project terminal window open at `username@device:~/fedora-docs/name-of-project`.
 
 * .adoc file contents window.
 
-
 The above layout allows you to quickly select files, make edits, and issue git and preview commands, all within the same tool.
 
 == Preview your work
 
-. In the terminal, navigate to your project folder. Type and enter this command:
+The _docsbuilder_ script uses Podman to build a preview of your docs pages in an isolated container.
+
+. In the terminal, navigate to your project folder. Run the _docsbuilder_ script by entering this command:
 +
 ----
 ./docsbuilder.sh
 ----
 +
-[EXPLANATION]
-====
-The ./docsbuilder script starts the Antora static site generator locally on your device within an isolated container.
-There is no requirement to install Antora or any other web development tools on your device.
-====
+A successful output will resemble this:
++
+----
+...
+Watching current directory (excluding: build/|cache/|preview.pid|public/|\.git.*|4913) for changes and re-building as required. Use Ctrl C to stop.
+Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...
+----
 
 . In a browser, visit http://localhost:8080.
 
@@ -119,42 +144,60 @@ There is no requirement to install Antora or any other web development tools on
 .. Save the .adoc file you have been editing and observe the script complete again.
 .. Refresh the browser window.
 
-== Pushing your changes to your remote fork in Forge
+NOTE: On MacOS, the _docsbuilder_ script uses Docker instead of Podman. You can install Docker from the official https://www.docker.com/[Docker Website].
 
-1. Add the changes to your local git staging ground:
+See xref:contributing-docs/tools-edit-local-clone.adoc#_the_docsbuilder_script_and_podman[here] for further information on the docsbuilder script.
+
+== Pushing your changes to your remote fork on Forge
+
+1. Determine the files that have been changed and added to the branch you are working on:
 +
 ----
-git add .
+git status
+----
++
+****
+The files in the output are known as 'untracked files', meaning that git has no idea what to do with these files or if you want them to be included in your commit.
+****
+2. Add the changed files to your local git staging ground:
++
+----
+git add <path-to-changed-file>
 ----
 
-2. Commit with a message:
+3. Commit with a message:
 +
 ----
 git commit -m <meaningful-name-reflecting-what-you-changed>
 ----
 
-3. Push your changes:
+4. Push your changes:
 +
 ----
 git push origin <branch-name>
 ----
 
-You are now ready to open a pull request.
+You are now ready to open a pull request (PR).
 
-== PR Checklist
+== PR checklist
 * [ ] Spelling and grammar checked.
 
 * [ ] Metadata and author tags entered.
 
 * [ ] Tested and previewed using the ./docsbuilder script.
 
+== Opening a pull request
 
-== Opening a Pull Request
-
-On the Forge web interface, navigate to your fork's repo and the branch you have been working.
-Use the click button to open the Pull request.
-
-
+On the Forge web interface, navigate to your fork's repo and the branch you have been working on.
+Click on the _New Pull Request_ button.
 
+== The docsbuilder script and Podman
 
+The _docsbuilder_ script is present in your local clone's project folder by default.
+Running the script starts the Antora static site generator locally on your device within an isolated container.
+There is no requirement to install Antora or any other web development tools on your device.
 
+Podman is an open source container tool similar to Docker.
+When you run the docsbuilder.sh script, Podman will download the Antora parser to your local machine as a container.
+Once you are done with the container, if you wish to remove it, simply run ``podman image rm antora``.
+There is no harm in leaving the container on your system if you are working on a lot of docs. This will allow you to save some bandwidth on the hosting server for the image.