Merge pull request #74 from erinann/master

updating How To docs 1 and 2

How_to_contribute/1_suggested_setup.adoc

@@ -1,7 +1,7 @@
 = Suggested setup to contribute to the ICES WGFAST conventions
 Erin LaBrecque
-:revnumber: 0.02
-:revdate: 2020-03-18
+:revnumber: 1.0
+:revdate: 2025-02-10
 :imagesdir: images\
 :toc: preamble
 :toclevels: 4
@@ -26,7 +26,7 @@ There is a lot of jargon surrounding Git and GitHub, but that is normal in any s
 == Software, accounts, and languages
 === Software to install
 *Git* - A distributed version control system. +
-*AsciidocFX* or *Atom* or *Brackets* - Modern text editors/Integrated Development Environments (IDEs). AsciidocFX, Atom, and Brackets can open, edit, and live preview AsciiDoc files. +
+*AsciidocFX* or *Visual Studio (VS) Code* - Modern text editors/Integrated Development Environments (IDEs). AsciidocFX and VS Code can open, edit, and live preview AsciiDoc files. +
 
 If you prefer to work online (in GitHub), you will not need a text editor. However, we suggest using a text editor if you are going to do more than fix a few spelling errors. +
 
@@ -40,15 +40,15 @@ AsciiDoc is a popular and flexible plain text markup language. Both convention d
 *Markdown* - extension `.md` +
 Markdown is the most popular plain text markup language but it is not as flexible as AsciiDoc. You will see a couple documents in the `wg_WGFAST` repository with `.md` extensions (eg - `README.md`). These are written in Markdown. GitHub automatically renders Markdown files into HTML.
 
-AsciidocFX, Atom, and Brackets can open, edit, and live preview AsciiDoc and Markdown files. +
+AsciidocFX and VS Code can open, edit, and live preview AsciiDoc and Markdown files. +
 
 == Suggested order of setup
 If you do not have any of the software or accounts listed in the section above, this is the most painless way to get started.
 
 1. Create a GitHub account. See the link:3_github_help.adoc[GitHub Help] file.
 2. Install Git. See the link:4_git_help.adoc[Git Help] file.
-3. Install AsciidocFX or Atom or Brackets and the necessary packages or extensions to read `.adoc` and `.md` files. See link:5_plain_text_editor_help.adoc[Text editors/IDEs help] file.
-4. Learn a little about AsciiDoc markup. See the link:asciidoc_help.adoc[AsciiDoc Help] file. +
+3. Install AsciidocFX or VS Code and the necessary packages or extensions to read `.adoc` and `.md` files. See link:5_plain_text_editor_help.adoc[Text editors/IDEs help] file.
+4. Learn a little about AsciiDoc markup. See the link:6_asciidoc_help.adoc[AsciiDoc Help] file. +
 {empty} +
 
 

How_to_contribute/2_suggested_workflow.adoc

@@ -1,7 +1,7 @@
 = Suggested workflow to contribute to the ICES WGFAST conventions
 Erin LaBrecque
-:revnumber: 0.02
-:revdate: 2020-03-18
+:revnumber: 1.0
+:revdate: 2025-02-10
 :imagesdir: images\
 :toc: preamble
 :toclevels: 4
@@ -27,7 +27,7 @@ We are going to use a workflow called *_Fork-Branch-Pull Request_*. A list and g
 .A few things to remember
 . This document might seem overwhelming at first. Do not worry. You can get through it. Take it one step at a time. You do not have to go through all the help files at once.
 . If you have questions or if anything is unclear, open an https://github.com/ices-eg/wg_WGFAST/issues[issue] and submit your question(s). Add `@erinann` to the issue and I will be notified.
-. You cannot break anything in the `ices-eg/wg_WGFAST` repository. Permissions are set so only the convention coordinators can wreak any havoc.
+. You cannot break anything in the `ices-eg/wg_WGFAST` repository. Permissions are set so only the convention coordinators can wreak havoc.
 . If you crash your remote repository beyond repair, do not worry. Delete it and fork another one.
 . If you would like to practice your Git skills before working on the `wg_WGFAST` repository, fork https://github.com/erinann/FAST_doc_tests and have a go!
 . All Git commands start with `git`.
@@ -37,18 +37,15 @@ We are going to use a workflow called *_Fork-Branch-Pull Request_*. A list and g
 [NOTE]
 ====
 *We recommend that you learn Git from the command line first because it will give you a better understanding of Git's functionality.* This workflow is written to use Git commands in a terminal.
-
-If you cannot get comfortable working at a command line, link:Atom_Git_GUI.adoc[How to use Git/GitHub GUI in Atom] and link:Brackets_Git_GUI.adoc[How to use Git/GitHub GUI in Brackets] will show you how to use the Atom and Brackets Git/GitHub GUIs. If you decide to use the GUIs, *please still read through this file as it provides an overview of the entire workflow*.
 ====
 {empty} +
 
 
 === Fork the ices-eg/wg_WGFAST repository
 * You only have to do this step once.
 - Sign into https://github.com[GitHub] and navigate to the ICES Expert Groups - wg_WGFAST repository at https://github.com/ices-eg/wg_WGFAST.
-- Fork the repository to your account by clicking on the image:fork_button.png[] button.
+- Fork the repository to your account by clicking on the fork button. image:fork_button.png[]
 
-image:fork_page.png[]
 {empty} +
 {empty} +
 
@@ -60,12 +57,12 @@ Once the repository is forked to your GitHub account you can either <<Editing do
 === Clone the forked repository to your computer
 * You only have to do this step once.
 ** Click on the repository to open it.
-** Click on the clone button. Use `Clone with HTTPS`.
+** Click on the Code button. Use `HTTPS`.
 ** Click on the clipboard button to save the URL to the clipboard.
 
 //
 
-1. Clone button.
+1. Code button.
 2. Clipboard button. This places a copy of the repository's URL on your clipboard. +
 
 image:clone_button.png[] +
@@ -111,12 +108,12 @@ The output means that a directory called `wg_WGFAST` was created on the computer
 [start=3]
 3. After the local repository is on your computer, change directories again to enter it by typing `cd wg_WGFAST`. You have to be in the local repository to work on it. When you are in the repository, the branch name will be in parentheses at the end of the pathname.
 
-.Example in Git Bash terminal, Windows 10
+.Example in Git Bash terminal, Windows 10 or 11
 image:BASH_terminal_git_clone.png[] +
 {empty} +
 
 
-=== Add the upstream repository
+=== Add changes from the upstream repository 
 You now have a copy of the forked repository on your computer, but what happens if there are changes in the upstream repository? How do you get those changes to your local repository? Remember, the upstream repository is the repository you forked from. The remote repository is in your GitHub account. The local repository is the repository on your computer. You need to tell Git what the upstream repository is in order to pull changes from it. This is called "adding the upstream repository" or "adding a remote".
 
 .List the current configured remote repository +
@@ -188,30 +185,8 @@ Time to step away from the terminal and open your text editor/IDE.
 
 Now that the repository is on your computer, add it to a workspace in text editor/IDE you chose, and check that you are on the correct branch.
 
-.*AsciidocFX*: +
-. Click on the image:ADFX_folder_icon.png[] and navigate to the folder.
-. Open the terminal. The active branch will be in parentheses at the end of the pathname.
-{empty} +
-
-.*Atom*: +
-. `File > Add Project Folder...` and navigate to the folder.
-. Look in the lower-right corner. There should be four icons: Branch, Publish (or Push), GitHub, and Git. Your branch name should be listed next to the branch icon. If it is not, click on the icon to open and drop down menu and select your working branch. +
-image:Atom_branch_check.png[] +
-{empty} +
-
-.*Brackets*: The _Brackets-Git_ extension has to be installed
-. `File > Open Folder...` and navigate to the folder.
-. Look in the upper-left corner below the File Menu bar. You  should see the branch icon and your branch name. If your working branch is not listed, click on the down arrow and select your working branch. +
-image:Brackets_branch_check.png[] +
-{empty} +
-
-You will have to add packages in Atom and extensions in Brackets to preview AsciiDoc files. Please see link:5_plain_text_editor_help.adoc[Text editors/IDEs help]. +
-{empty} +
 
 
-NOTE: Citation preview does not currently work in Atom or Brackets. Math equation (LaTex math) preview does not currently work in Atom, but you can change the settings of the AsciiDoc Preview extension in Brackets to preview math equations. +
-{empty} +
-
 === Edit
 Open an AsciiDoc document in AsciidocFX, Atom, or Brackets and start editing. +
 image:editing_2.jpg[height=150, width=150] +

How_to_contribute/5_plain_text_editor_help.adoc

@@ -55,72 +55,6 @@ image:AsciidocFX_panes.png[]
 
 TIP: The default editor theme has a white background. You can change the theme to "Dark" in the `Settings -> Editor Settings` tab.
 
-== https://atom.io/[Atom]
-image:Atom-logo.svg[width = 50, height = 50] +
-Atom is supported on macOS, Windows, and Linux.
-
-=== Installing Atom
-To install Atom, click the big, yellow "Download" button at https://atom.io/[Atom.io] and run the installer. If the operating system listed above the download button is not your operating system, you can find other builds and releases at https://github.com/atom/atom (scroll down). +
-
-==== Packages
-To preview AsciiDoc and Markdown documents you will have to install a few packages. +
-
-From the Welcome Page you can click on `Install a Package` or go to `File -> Settings` and click on `Install` at the bottom of the list of options.
-
-.Packages to install
-* asciidoc-assistant +
- Installs the following packages:
-** asciidoc-image-helper +
- Provides the ability to past images from the clipboard.
-** asciidoc-preview +
- Shows an HTML preview for the AsciiDoc content in the current editor.
-** autocomplete-asciidoc +
- AsciiDoc language autocompletions.
-** language-asciidoc +
- Syntax highlighting and snippets for AsciiDoc.
-
-* Other packages you might want
-** markdown-preview-plus +
- To show an HTML preview of Markdown (`.md`) documents.
-** atom-terminal +
- Opens an external terminal in the current directory. +
-** terminal-tab
- Opens a terminal pane within Atom in the current directory.
-
-_You do not need both `atom-terminal` and `terminal-tab`. One or the other will do._ +
-
-
-NOTE: If asciidoc-assistant failed to install any of its dependencies, you will have to install those package separately.
-
-==== Useful shortcuts
-* `Ctrl+Shift+P` (Linux/Windows) or `cmd+shift+P` (macOS). Opens the Command Pallet where you can find and run available commands.
-* `Ctrl+Shift+A` (Linux/Windows) or `cmd+shift+A` (macOS). Opens AsciiDoc live preview. +
-* `Ctrl+Shift+M` (Linux/Windows) or `cmd+shift+M` (macOS). Opens Markdown live preview. +
-{empty} +
-
-=== Panes
-Atom is a little friendlier in that it opens to a "Welcome Page" with links to help get you started. You can turn this option off by un-checking the box next to "Show Welcome Guide when opening Atom".
-
-image:Atom_panes_welcome.png[] +
-{empty} +
-
-
-image:Atom_panes_working.png[] +
-{empty} +
-
-=== Integration with Git and GitHub
-Atom comes bundled with a GUI for Git and GitHub. You have to supply your GitHub login credentials the first time you push commits to GitHub with the GUI. +
-
-To work in a terminal, you have to install an external package. There are a number of Atom packages that give you access to a terminal. The simplest is `atom-terminal` which opens your external terminal in the root directly of the project. `terminal-tab` opens a terminal within Atom that you can dock in different places, but the package can be a little flaky - closing the terminal by clicking the `x` to close the tab instead of exiting out of the terminal (typing `exit` at the command line) crashes Atom.
-
-Instructions for working with Git in a terminal are in the link:2_suggested_workflow.adoc[Suggested workflow to contribute to the ICES WGFAST convention documents] file.
-
-==== Git terminal from Atom
-1. Open the settings of the terminal package you installed and make sure the path to your terminal is correct.
-2. Open the terminal when you need to stage, commit, and push to GitHub.
-
-==== Git/GitHub GUI in Atom
-Please see link:Atom_Git_GUI.adoc[How to use Git/GitHub GUI in Atom]
 
 
 == http://brackets.io/[Brackets]