From 1fe1834960bed8ba03731612339ce03cd61f4260 Mon Sep 17 00:00:00 2001 From: grammaresque Date: Mon, 5 Dec 2022 15:41:36 -0600 Subject: [PATCH 01/11] general proofreading --- docs/books/admin_guide/03-commands.md | 188 +++++++++++++------------- 1 file changed, 93 insertions(+), 95 deletions(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index de995e5c32..1e90376efd 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -1,20 +1,20 @@ --- title: Linux Commands author: Antoine Le Morvan -contributors: Steven Spencer, Aditya Putta, tianci li +contributors: Steven Spencer, Aditya Putta, tianci li, Grammaresque --- # Commands for Linux Users -In this chapter you will learn how to work with Linux with the commands. +In this chapter you will learn Linux commands and how to use them. **** **Objectives**: In this chapter, future Linux administrators will learn how to: -:heavy_check_mark: **move** in the system tree; -:heavy_check_mark: **create** a text file, **display** its contents and **modify** it; -:heavy_check_mark: use the most useful Linux commands. +:heavy_check_mark: **Move** within the system tree. +:heavy_check_mark: **Create** a text file, **display** its contents and **modify** it. +:heavy_check_mark: **Use** the most useful Linux commands. :checkered_flag: **user commands**, **linux** @@ -35,42 +35,42 @@ Current Linux systems have graphical utilities dedicated to the work of an admin * In order to preserve server resources, the graphical interface is either not installed or launched on demand. * Administration is done by scripts. -Learning these commands allows the administrator to connect to a Linux terminal, to manage its resources, its files, to identify the station, the terminal, and the connected users, etc. +Learning these commands allows the administrator to connect to a Linux terminal, to manage its resources and files, to identify the station, the terminal, and the connected users, etc. ### The users -The user of a Linux system is defined in the `/etc/passwd` file, by: +The user of a Linux system will be defined in the `/etc/passwd` file, by: -* a **login name**, more commonly called "login", containing no spaces; -* a numeric identifier: **UID** (User Identifier); -* a group identifier: **GID** (Group Identifier); -* a **command interpreter**, a shell, which can be different from one user to another; -* a **connection directory**, the __home directory__. +* A **login name**, more commonly called "login", containing no spaces. +* A numeric identifier: **UID** (User Identifier). +* A group identifier: **GID** (Group Identifier). +* A **command interpreter**, e.g., a shell, which can be different from one user to another. +* A **connection directory**, e.g., the __home directory__. -In other files by: +In other files the user will be defined by: -* a **password**, which will be encrypted before being stored (`/etc/shadow`); -* a **command prompt**, or __prompt__ login, which will be symbolized by a `#` for administrators and a `$` for other users (`/etc/profile`). +* A **password**, which is encrypted before being stored (`/etc/shadow`). +* A **command prompt**, or __prompt__ login, which is symbolized by a `#` for administrators and a `$` for other users (`/etc/profile`). -Depending on the security policy implemented on the system, the password will have to contain a certain number of characters and meet certain complexity requirements. +Depending on the security policy implemented on the system, the password will require a certain number of characters and meet certain complexity requirements. -Among the existing command interpreters, the **Bourne-Again Shell** (`/bin/bash`) is the one most frequently used. It is assigned by default to new users. For various reasons, advanced Linux users can choose alternative shells from among the Korn Shell (`ksh`), the C Shell (`csh`), etc. +Among the existing command interpreters, the **Bourne-Again Shell** (`/bin/bash`) is the one most frequently used. It is assigned by default to new users. For various reasons, advanced Linux users can choose alternative shells such as the Korn Shell (`ksh`), the C Shell (`csh`), etc. The user's login directory is by convention stored in the `/home` directory of the workstation. It will contain the user's personal data and the configuration files of his applications. By default, at login, the login directory is selected as the current directory. -A workstation type installation (with graphical interface) starts this interface on terminal 1. Linux being multi-user, it is possible to connect several users several times, on different **physical terminals** (TTY) or **virtual terminals** (PTS). Virtual terminals are available within a graphical environment. A user switches from one physical terminal to another using Alt + Fx from the command line or using CTRL + Alt + Fx. +A workstation-type installation (with graphical interface) starts this interface on terminal 1. Linux being multi-user, it is possible to connect several users several times, on different **physical terminals** (TTY) or **virtual terminals** (PTS). Virtual terminals are available within a graphical environment. A user switches from one physical terminal to another using Alt + Fx from the command line or using CTRL + Alt + Fx. ### The shell -Once the user is connected to a console, the shell displays the command **prompt**. It then behaves like an infinite loop, with each statement entered: +Once the user is connected to a console, the shell displays the **command prompt**. It then behaves like an infinite loop, repeating the same pattern with each statement entered: -* displaying the command prompt; -* reading the command; -* syntax analysis; -* substitution of special characters; -* execute the command; -* display the command prompt; -* etc. +* Display the command prompt. +* Reading the command. +* Analyze syntax. +* Substitute special characters. +* Execute the command. +* Display the command prompt. +* Etc. The key sequence CTRL + C is used to interrupt a running command. @@ -80,7 +80,7 @@ The use of a command generally follows this sequence: command [option(s)] [arguments(s)] ``` -The name of the command is **often in lower case**. +The name of the command is often **lower case**. A space separates each item. @@ -99,7 +99,7 @@ is equivalent to: $ ls -lia ``` -There can of course be several arguments after an option: +There can be several arguments after an option: ```bash $ ls -lia /etc /home /var @@ -134,7 +134,7 @@ clearerr_unlocked (3) - nonlocking stdio functions feclearexcept (3) - floating-point rounding and exception handling fwup_clear_status (3) - library to support management of system firmware updates klogctl (3) - read and/or clear kernel message ring buffer; set console_loglevel -sgt-samegame (6) - Block-clearing puzzle +sgt-samegame (6) - block-clearing puzzle syslog (2) - read and/or clear kernel message ring buffer; set console_loglevel timerclear (3) - timeval operations XClearArea (3) - clear area or window @@ -170,14 +170,14 @@ clear (1) - clear the terminal screen Once found by `apropos` or `whatis`, the manual is read by `man` ("Man is your friend"). This set of manuals is divided into 8 sections, grouping information by topic, the default section being 1: -1. Executable programs or commands; -2. System calls (functions given by the kernel); -3. Library calls (functions given by the library); -4. Special files (usually found in /dev); -5. File Formats and conventions (configuration files such as etc/passwd); -6. Games (such as character-based applications); -7. Miscellaneous (e.g. man (7)); -8. System administration commands (usually only for root); +1. Executable programs or commands. +2. System calls (functions given by the kernel). +3. Library calls (functions given by the library). +4. Special files (usually found in /dev). +5. File Formats and conventions (configuration files such as etc/passwd). +6. Games (such as character-based applications). +7. Miscellaneous (e.g. man (7)). +8. System administration commands (usually only for root). 9. Kernel routines (non-standard). Information about each section can be accessed by typing `man x intro`, where `x` is the section number. @@ -196,21 +196,19 @@ $ man 5 passwd will inform him about the files related to the command. -Not all manual pages are translated from English. However, English manual pages are usually very accurate and provide all the information you need. The grammar and separation rules it uses may confuse beginner administrators, but after practice, I'm sure you'll find the information you want. - -The navigation in the manual is done with the arrows ↑ and ↓. The manual is exited by pressing the q key. +Navigate through the manual with the arrows ↑ and ↓. Exit the manual by pressing the q key. ### `shutdown` command -The `shutdown` command allows you to **electrically shut down** a Linux server, either immediately or after a certain period of time. +The `shutdown` command allows you to **electronically shut down** a Linux server, either immediately or after a certain period of time. ```bash shutdown [-h] [-r] time [message] ``` -The shutdown time should be specified in the format `hh:mm` for a precise time, or `+mm` for a delay in minutes. +Specify the shutdown time in the format `hh:mm` for a precise time, or `+mm` for a delay in minutes. -To force an immediate stop, the word `now` will replace the time. In this case, the optional message is not sent to other users of the system. +To force an immediate stop, use the word `now` in place of the time. In this case, the optional message is not sent to other users of the system. Examples: @@ -223,8 +221,8 @@ Options: | Options | Remarks | | ------- | -------------------------------- | -| `-h` | Shutdown the system electrically | -| `-r` | Restarts the system | +| `-h` | Shuts down the system electronically. | +| `-r` | Restarts the system. | ### `history` command @@ -242,8 +240,8 @@ $ history | Options | Comments | | ------- | ------------------------------------------------------------------------------------------------------------------ | -| `-w` | Write the current history to the history file | -| `-c` | The `-c` option will delete the history of the current session (but not the contents of the `.bash_history` file). | +| `-w` | Writes the current history to the history file. | +| `-c` | Deletes the history of the current session (but not the contents of the `.bash_history` file). | * Manipulating history: @@ -251,29 +249,29 @@ To manipulate the history, the following commands entered from the command promp | Keys | Function | | ------------------ | --------------------------------------------------------- | -| !! | Recall the last command placed. | -| !n | Recall the command by its number in the list. | -| !string | Recall the most recent command beginning with the string. | -| ↑ | Recall the most recent command beginning with the string. | -| ↓ | Recall the most recent command beginning with the string. | +| !! | Recalls the last command placed. | +| !n | Recalls the command by its number in the list. | +| !string | Recalls the most recent command beginning with the string. | +| ↑ | Navigates through your history working backward in time from the most recent command. | +| ↓ | Navigates through your history working forward in time. | -### The auto-completion +### Auto-complete -Auto-completion is also a great help. +Auto-completion is a great help. -* It allows you to complete commands, entered paths, or file names. -* A press of the TAB key completes the entry in the case of a single solution. -* Otherwise, a second press will be required to obtain the list of possibilities. +* Completes commands, entered paths, or file names. +* Press the TAB key to complete the entry in the case of a single solution. +* In the case of multiple solutions, press TAB a second time to see options. -If a double press of the TAB key causes no reaction from the system, then there is no solution to the current completion. +If double-pressing the TAB key presents no options, then there is no solution to the current completion. -## Display and identification +## Display and Identification ### `clear` command -The `clear` command clears the contents of the terminal screen. In fact, to be more precise, it shifts the display so that the command prompt is at the top of the screen on the first line. +The `clear` command clears the contents of the terminal screen. More accurately, it shifts the display so that the command prompt is at the top of the screen on the first line. -In a terminal, the display will be permanently hidden, whereas in a graphical interface, a scrollbar will allow you to go back in the history of the virtual terminal. +On a physical terminal, the display will be permanently hidden, whereas in a graphical interface, a scrollbar will allow you to go back in the history of the virtual terminal. !!! Tip @@ -302,11 +300,11 @@ Among the frequently used sequences, we can mention: | Sequence | Result | | -------- | --------------------- | -| `\a` | Send a sonor bip | +| `\a` | Sends a sonar beep | | `\b` | Back | | `\n` | Adds a line break | | `\t` | Adds a horizontal tab | -| `\v` | Adds vertical tab | +| `\v` | Adds a vertical tab | ### `date` command @@ -386,14 +384,14 @@ rockstar tty1 2021-05-24 10:30 root pts/0 2021-05-24 10:31 ``` -Since Linux is multi-user, it is likely that multiple sessions are open on the same station, either physically or over the network. It is interesting to know which users are logged in, if only to communicate with them by sending messages. +Since Linux is multi-user, it is possible that multiple sessions are open on the same station, either physically or over the network. It is interesting to know which users are logged in, if only to communicate with them by sending messages. * tty: represents a terminal. * pts/: represents a virtual console in a graphical environment with the number after representing the instance of the virtual console (0, 1, 2...) The `-r` option also displays the runlevel (see chapter "startup"). -## File tree +## File Tree In Linux, the file tree is an inverted tree, called a **single hierarchical tree**, whose root is the directory `/`. @@ -438,13 +436,13 @@ $ pwd /home/rockstar ``` -Use a relative path to reference a file or directory, or use the `cd` command to move to another directory, You must know its location in the file tree. +To use a relative path to reference a file or directory, or use the `cd` command to move to another directory, you must know its location in the file tree. Depending on the type of shell and the different parameters of its configuration file, the terminal prompt (also known as the command prompt) will display the absolute or relative path of the current directory. ### `cd` command -The `cd` (Change Directory) command allows you to change the current directory, in other words, to move through the tree. +The `cd` (Change Directory) command allows you to change the current directory -- in other words, to move through the tree. ```bash $ cd /tmp @@ -481,7 +479,7 @@ The main options of the `ls` command are: | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `-a` | Displays all files, even hidden ones. Hidden files in Linux are those beginning with `.`. | | `-i` | Displays inode numbers. | -| `-l` | The `-l` command displays a vertical list of files with additional information formatted in columns. | +| `-l` | Displays a vertical list of files with additional information formatted in columns. | The `ls` command, however, has a lot of options (see `man`): @@ -494,9 +492,9 @@ The `ls` command, however, has a lot of options (see `man`): | `-A` | Displays all files in the directory except `.` and `..` | | `-R` | Displays the contents of subdirectories recursively. | | `-F` | Displays the type of files. Prints a `/` for a directory, `*` for executables, `@` for a symbolic link, and nothing for a text file. | -| `-X` | Sort files according to their extensions. | +| `-X` | Sorts files according to their extensions. | -* Description of columns: +* Description of columns generated by running the `ls -lia` command: ```bash $ ls -lia /home @@ -524,7 +522,7 @@ $ ls -lia /home alias ll='ls -l --color=auto' ``` -The `ls` command has many options and here are some advanced examples of uses: +The `ls` command has many options. Here are some advanced examples of uses: * List the files in `/etc` in order of last modification: @@ -559,7 +557,7 @@ $ find /var -size +1M -a -size -1024M -a -type f -exec ls -lh {} \; * Show the rights on a folder: -To find out the rights to a folder, in our example `/etc`, the following command would not be appropriate: +To find out the rights to a folder, in our example `/etc`, the following command would **not** be appropriate: ```bash $ ls -l /etc @@ -693,7 +691,7 @@ rm [-f] [-r] file [file] [...] !!! Note - The `rm` command itself does not ask for confirmation when deleting files. However, with a RedHat/Rocky distribution, `rm` does ask for confirmation of deletion because the `rm` command is an `alias` of the `rm -i` command. Don't be surprised if on another distribution, like Debian for example, you don't get a confirmation request. + The `rm` command itself does not ask for confirmation when deleting files. However, with a Red Hat/Rocky distribution, `rm` does ask for confirmation of deletion because the `rm` command is an `alias` of the `rm -i` command. Don't be surprised if on another distribution, like Debian for example, you don't get a confirmation request. Deleting a folder with the `rm` command, whether the folder is empty or not, will require the `-r` option to be added. @@ -993,12 +991,12 @@ adm:x:3:4:adm:/var/adm/:/sbin/nologin | Option | Description | | --------- | ------------------------------------------- | -| `-k` | Specify the columns to be separated. You can specify multiple columns | -| `-n` | Requests a numeric sort | -| `-o file` | Saves the sort to the specified file | -| `-t` | Specify a delimiter, which requires that the contents of the corresponding file must be regularly delimited column contents, otherwise they cannot be sorted properly | -| `-r` | Reverse the order of the result. Used in conjunction with the `-n` option to sort in order from largest to smallest | -| `-u` | Remove duplicates after sorting. Equivalent to `sort file | uniq` | +| `-k` | Specify the columns to be separated. You can specify multiple columns. | +| `-n` | Requests a numeric sort. | +| `-o file` | Saves the sort to the specified file. | +| `-t` | Specify a delimiter, which requires that the contents of the corresponding file must be regularly delimited column contents, otherwise they cannot be sorted properly. | +| `-r` | Reverse the order of the result. Used in conjunction with the `-n` option to sort in order from largest to smallest. | +| `-u` | Remove duplicates after sorting. Equivalent to `sort file | uniq`. | The `sort` command sorts the file only on the screen. The file is not modified by the sorting. To save the sort, use the `-o` option or an output redirection `>`. @@ -1013,7 +1011,7 @@ systemd-coredump:x:999:997:systemd Core Dumper:/:/sbin/nologin polkitd:x:998:996:User for polkitd:/:/sbin/nologin ``` -In this example, the `sort` command will sort the contents of the `/etc/passwd` file this time from largest uid to smallest. +In this example, the `sort` command will sort the contents of the `/etc/passwd` file this time from largest uid (user identifier) to smallest. Some advanced examples of using the `sort` command: @@ -1076,29 +1074,29 @@ The `sort` command knows how to recognize file sizes, from commands like `ls` wi Here is an example with the file `size.txt`: ``` -1,7G +1.7G 18M 69K -2,4M -1,2M -4,2G +2.4M +1.2M +4.2G 6M 124M -12,4M +12.4M 4G ``` ```bash $ sort -hr size.txt -4,2G +4.2G 4G -1,7G +1.7G 124M 18M -12,4M +12.4M 6M -2,4M -1,2M +2.4M +1.2M 69K ``` @@ -1181,7 +1179,7 @@ ls: /bin/ls | Option | Description | | ------ | ------------------------------- | -| `-b` | Search only the binary file. | +| `-b` | Searches only the binary file. | | `-m` | Searches only for man pages. | | `-s` | Searches only for source files. | @@ -1202,9 +1200,9 @@ root:x:0:0:root:/root:/bin/bash | Option | Description | | --------------------------------------------------------------------------------------- | --------------------------------------- | -| `-i` | Ignore the case of the searched string. | +| `-i` | Ignores the case of the searched string. | | `-v` | Excludes lines containing the string. | -| `-w` | Search for the exact word. | +| `-w` | Searches for the exact word. | The `grep` command returns the complete line containing the string you are looking for. * The `^` special character is used to search for a string at the beginning of a line. @@ -1429,7 +1427,7 @@ Search for a string in the result: $ ls -lia / | grep fichier ``` -## Special points +## Special Points ### `tee` command @@ -1523,7 +1521,7 @@ $ \ls file* # order by name file1.txt file2.txt file3.txt ``` -### Aliases and useful functions +### Aliases and Useful Functions * `grep` alias. From 0129025f033096402f8febcc89691a16c7118c44 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Mon, 5 Dec 2022 22:17:01 -0600 Subject: [PATCH 02/11] Update docs/books/admin_guide/03-commands.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/books/admin_guide/03-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index 1e90376efd..4379cc393c 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -69,7 +69,7 @@ Once the user is connected to a console, the shell displays the **command prompt * Analyze syntax. * Substitute special characters. * Execute the command. -* Display the command prompt. +* Displays the command prompt. * Etc. The key sequence CTRL + C is used to interrupt a running command. From 2ffe2b618d74ac3d99a8a8c6f0aa4d0c070e86c3 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Mon, 5 Dec 2022 22:17:24 -0600 Subject: [PATCH 03/11] Update docs/books/admin_guide/03-commands.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/books/admin_guide/03-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index 4379cc393c..42dc2ac0e5 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -64,7 +64,7 @@ A workstation-type installation (with graphical interface) starts this interface Once the user is connected to a console, the shell displays the **command prompt**. It then behaves like an infinite loop, repeating the same pattern with each statement entered: -* Display the command prompt. +* Displays the command prompt. * Reading the command. * Analyze syntax. * Substitute special characters. From 5c2f19111d758af9cf329a90d374b3c94ea6a2e8 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Mon, 5 Dec 2022 22:18:16 -0600 Subject: [PATCH 04/11] Update docs/books/admin_guide/03-commands.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix "Readings" Co-authored-by: Serge Croisé --- docs/books/admin_guide/03-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index 42dc2ac0e5..7c033f7c3d 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -65,7 +65,7 @@ A workstation-type installation (with graphical interface) starts this interface Once the user is connected to a console, the shell displays the **command prompt**. It then behaves like an infinite loop, repeating the same pattern with each statement entered: * Displays the command prompt. -* Reading the command. +* Reads the command. * Analyze syntax. * Substitute special characters. * Execute the command. From 80bcee46aefc326a84ff30b15cd2ee703e446492 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Mon, 5 Dec 2022 22:19:43 -0600 Subject: [PATCH 05/11] Update docs/books/admin_guide/03-commands.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix "Analyzes the..." Co-authored-by: Serge Croisé --- docs/books/admin_guide/03-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index 7c033f7c3d..7996c70762 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -66,7 +66,7 @@ Once the user is connected to a console, the shell displays the **command prompt * Displays the command prompt. * Reads the command. -* Analyze syntax. +* Analyzes the syntax. * Substitute special characters. * Execute the command. * Displays the command prompt. From 4880eba0e374922f2f0a6660a771a2b7aeb4b202 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Mon, 5 Dec 2022 22:20:30 -0600 Subject: [PATCH 06/11] Update docs/books/admin_guide/03-commands.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Substitute to Substitutes... Co-authored-by: Serge Croisé --- docs/books/admin_guide/03-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index 7996c70762..04847af64b 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -67,7 +67,7 @@ Once the user is connected to a console, the shell displays the **command prompt * Displays the command prompt. * Reads the command. * Analyzes the syntax. -* Substitute special characters. +* Substitutes special characters. * Execute the command. * Displays the command prompt. * Etc. From c3f0cb4a1f413aa2c5adca58fb83ed5725608de2 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Mon, 5 Dec 2022 22:23:43 -0600 Subject: [PATCH 07/11] Update 03-commands.md Update "Execute" to "Executes" --- docs/books/admin_guide/03-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/books/admin_guide/03-commands.md b/docs/books/admin_guide/03-commands.md index 04847af64b..60aba8b3db 100644 --- a/docs/books/admin_guide/03-commands.md +++ b/docs/books/admin_guide/03-commands.md @@ -68,7 +68,7 @@ Once the user is connected to a console, the shell displays the **command prompt * Reads the command. * Analyzes the syntax. * Substitutes special characters. -* Execute the command. +* Executes the command. * Displays the command prompt. * Etc. From b4d57a73ca399f5244829c8b49bd9e4109237a37 Mon Sep 17 00:00:00 2001 From: grammaresque Date: Fri, 9 Dec 2022 12:53:02 -0600 Subject: [PATCH 08/11] basic proofreading --- .../books/admin_guide/04-advanced-commands.md | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/books/admin_guide/04-advanced-commands.md b/docs/books/admin_guide/04-advanced-commands.md index 148438976c..0de11f20d2 100644 --- a/docs/books/admin_guide/04-advanced-commands.md +++ b/docs/books/admin_guide/04-advanced-commands.md @@ -4,13 +4,13 @@ title: Advanced Linux Commands # Advanced Commands for Linux users -In this chapter you will learn some advanced commands for Linux. +Advanced commands provide greater customization and controls in more specialized situations once you become familiar with basic commands. **** **Objectives**: In this chapter, future Linux administrators will learn: -:heavy_check_mark: some useful commands not covered in the previous chapter; +:heavy_check_mark: some useful commands not covered in the previous chapter. :heavy_check_mark: some advanced commands. :checkered_flag: **user commands**, **Linux** @@ -41,9 +41,9 @@ steven !!! Note - `uniq` requires the input file to be sorted because it only compares consecutive lines. + `uniq` requires the input file to be sorted before running because it only compares consecutive lines. -Without an argument, the `uniq` command will not display identical lines that follow each other in the `firstnames.txt` file: +With no argument, the `uniq` command will not display identical lines that follow each other in the `firstnames.txt` file: ``` $ sort firstnames.txt | uniq @@ -60,7 +60,7 @@ $ sort firstnames.txt | uniq -u patrick ``` -Conversely, to display only the lines that appear at least twice in the file, you must use the `-d` option: +Conversely, to display only the lines that appear at least twice in the file, use the `-d` option: ``` $ sort firstnames.txt | uniq -d @@ -140,7 +140,7 @@ drwxrwxrwt. 3 root root 4096 6 avril 10:25 /tmp In practice, the `xargs` command executed the `ls -ld /home /tmp /root` command. -What happens if the command to be executed does not accept multiple arguments as is the case with the `find` command? +What happens if the command to be executed does not accept multiple arguments, such as with the `find` command? ``` $ xargs find /var/log -name @@ -175,7 +175,7 @@ $ xargs -L 1 find /var/log -name ``` -If we wanted to be able to specify both arguments on the same line, we would have to use the `-n 1` option: +To specify both arguments on the same line, use the `-n 1` option: ``` $ xargs -n 1 find /var/log -name @@ -204,34 +204,35 @@ $ tar tvfP /root/log.tar The special feature of the `xargs` command is that it places the input argument at the end of the called command. This works very well with the above example since the files passed in will form the list of files to be added to the archive. -Now, if we take the example of the `cp` command and want to copy a list of files in a directory, this list of files will be added at the end of the command... but what the `cp` command expects at the end of the command is the destination. To do this, we use the `-I` option to put the input arguments somewhere else than at the end of the line. +Using the example of the `cp` command, to copy a list of files in a directory, this list of files will be added at the end of the command... but what the `cp` command expects at the end of the command is the destination. To do this, use the `-I` option to put the input arguments somewhere else than at the end of the line. ``` $ find /var/log -type f -name "*.log" | xargs -I % cp % /root/backup ``` -The `-I` option allows you to specify a character (in our example the `%` character) where the input files to `xargs` will be placed. +The `-I` option allows you to specify a character (the `%` character in the above example) where the input files to `xargs` will be placed. ## `yum-utils` package -The `yum-utils` package is a collection of utilities from different authors for `yum`, which make it easier and more powerful to use. +The `yum-utils` package is a collection of utilities, built for `yum` by various authors, which make it easier and more powerful to use. !!! Note - While `yum` has been replaced by `dnf` in Rocky Linux 8, the package name has remained `yum-utils` although it can be installed as `dnf-utils` as well. These are classic YUM utilities implemented as CLI shims on top of DNF to maintain backwards compatibility with `yum-3`. + While `yum` has been replaced by `dnf` in Rocky Linux 8, the package name has remained `yum-utils`, although it can be installed as `dnf-utils` as well. These are classic YUM utilities implemented as CLI shims on top of DNF to maintain backwards compatibility with `yum-3`. -Here are some examples of usage: +Here are some examples of these utilities: -* `repoquery` command: +* `repoquery` command The `repoquery` command is used to query the packages in the repository. Examples of use: - * Display the dependencies of a package (it can be a software package that has been installed or not installed), equivalent to `dnf deplist `. - + * Display the dependencies of a package (it can be a software package that has been installed or not installed), equivalent to `dnf deplist ` + ``` repoquery --requires - + ``` + * Display the files provided by an installed package (does not work for packages that are not installed), equivalent to `rpm -ql ` ``` @@ -280,7 +281,7 @@ $ dnf download --downloadonly --downloaddir /var/tmp --resolve samba | Options | Comments | |-------------|-----------------------------------------------------------------| -| -`-destdir` | The downloaded packages will be stored in the specified folder. | +| `--destdir` | The downloaded packages will be stored in the specified folder. | | `--resolve` | Also downloads the package dependencies. | ## `psmisc` packages @@ -344,7 +345,7 @@ $ watch -n 5 tail -n 3 /etc/passwd Result: ``` -Every 5,0s: tail -n 3 /etc/passwd rockstar.rockylinux.lan: Thu Jul 1 15:43:59 2021 +Every 5.0s: tail -n 3 /etc/passwd rockstar.rockylinux.lan: Thu Jul 1 15:43:59 2021 sssd:x:996:993:User for sssd:/:/sbin/nologin chrony:x:995:992::/var/lib/chrony:/sbin/nologin From 61ab477adf12306336e34abca08cf1edc03aed82 Mon Sep 17 00:00:00 2001 From: grammaresque Date: Tue, 20 Dec 2022 15:29:14 -0600 Subject: [PATCH 09/11] fresh take on readme.md with two child docs --- README.md | 233 ++++++++++++++++++++++++++++++++------------------- beginners.md | 113 +++++++++++++++++++++++++ createnew.md | 49 +++++++++++ 3 files changed, 307 insertions(+), 88 deletions(-) create mode 100644 beginners.md create mode 100644 createnew.md diff --git a/README.md b/README.md index 5a54e31119..755395a736 100644 --- a/README.md +++ b/README.md @@ -3,94 +3,181 @@ [![All Contributors](https://img.shields.io/badge/all_contributors-80-orange.svg?style=flat-square)](#contributors-) + ## Introduction -So you want to contribute to the Rocky Linux documentation, but aren't sure how to go about that? You've come to the right place. We're excited to have you on board with us. +_With Rocky Linux emerging as a major RHEL-compatible distribution, this is an exciting time in the open source community. Rocky’s [mission](https://rockylinux.org/community-charter/) is to provide companies a **stable foundation of open source software** for their enterprise and HPC needs. We are here to support that mission with excellent documentation._ + +To us, excellent documentation hits these marks: + + + +* Educate users how to admin this distribution and its associated programs. +* Support users of all skill levels with manuals and troubleshooting guides to make the most of this distribution. +* Apply a consistent standard across all related documents, for ease of reading and translation. +* Keep documentation up to date (and error free) with current versions. +* Allow users to contribute Guides, Docs, Gemstones (scripts and favorite code snippets) and more, to enhance Rocky for fellow users. + +We welcome anyone who wants to be part of this mission. No specific degree, years of experience, or company affiliation required. Be bold! You won’t break anything even if you fumble your first attempt. Promise. + + +## Technical requirements + +_Our standards for Rocky documentation._ + +### Style Guide + +The RL [Style Guide](https://github.com/rocky-linux/documentation/blob/main/docs-style-guide/README.md) outlines standards for the wording within your document. + + +### GitHub + +Rocky Linux uses GitHub to manage its code and files, including documentation files. Login to GitHub and follow the official [Rocky Linux documentation repository](https://github.com/rocky-linux/documentation). + + +### Markdown + +Documentation is welcome in whatever format you are used to creating. It does not need to be perfect, just submit what you have and the team will give you feedback to help get it in line with our voice and tone. + +That said, RL Documentation uses Markdown as the standard. It is easy to learn and use. Run a text converter on your content or start from scratch with this [basic writing and formatting guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) by GitHub. + +As you become a regular contributor, you’ll need to create a **local repository**. See our [guide](link to the first time contributor guide, once published) for how to install a Markdown editor and create a local repository on your home computer. + + +## Contribution Process + +_The actual process of reporting an issue, revising, or creating a doc. Please see special notes afterward about translations, links, and meta content._ + + +### Report an issue + +Maybe you’ve found a broken link or incorrect information while exploring the Rocky docs. This is called an **issue**, and we want to know about it. You can mention it on the Mattermost Documentation channel, or visit GitHub and make a proper issue report. GitHub has [a handy guide](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) for how to create an issue. + + +### Submit an update + +_Add a missing word, correct an error, clarify a confusing bit of text. You won’t break anything because someone will review your contribution before it goes live. Here is the basic process._ + + + +1. Start on the page you want to update on [https://docs.rockylinux.org/](https://docs.rockylinux.org/). + +Click the “Edit” pencil in the upper right corner of the document. You will be taken to the original document stored on GitHub. + +The first time you contribute to the RL repository, you will be prompted with a green button to “**Fork** this **repository** and propose changes.” This creates a duplicate copy of the RL repository where you make your suggested edits. Click the green button and continue. + + + +2. Make your changes + +Follow the existing Markdown formatting. Make the necessary change. -One of our main goals for Rocky is to have not just good but GREAT documentation, and we cannot do it alone. This document will get you started and will (hopefully) ease any worries you might have about doing so. We will always be here to help, so feel free to ask questions and join in the conversation. -## Documentation Subjects -If you can dream it — or better yet, have done it before — then your subject is probably important to the Rocky Linux documentation project. +3. Propose changes -Where do you come in — both now and in the future? If you have experience with anything Linux-related and can translate that to Rocky Linux, we would like you to start writing! +At the bottom of the page, write a brief description in the title of the block entitled Propose changes. -## Where to Start +Then click Propose changes, which will **Commit** your changes to a completed document within your forked repository. -While you can create documentation in **any format** (seriously, we will accept it any way you create it), the preferred format is Markdown. You can easily create documents in Markdown, plus Markdown is super-easy to learn. The best way to get started with Markdown is to have a Markdown editor installed and read the tutorial. You can create Markdown files with any text editor, but most Markdown editors allow you to preview what you've input already, so they can be very helpful. -### Markdown Editor -As we've said already, the best way to create Markdown files, particularly if you've not done it before, is to grab an editor for the operating system that you use on your PC or Laptop. A simple web search for "Markdown editors" will show you a bunch to choose from. +4. Review changes -Pick one to use that is compatible with your Operating System. [ReText](https://github.com/retext-project/retext), a cross-platform Markdown editor, was used to create this document. Again, if you prefer to create your Markdown files in your text editor that you are already familiar with, that is just fine. +Now you can look at what you’ve done, line by line. If you missed anything, back up to the previous page and correct it again (you’ll have to start over), then click Propose Changes again. -#### Alternate Markdown Editors +Once the doc is the way you want it, click the green button that says Create Pull Request. This provides one more chance to double check your changes and confirm the doc is ready. -ReText is good, but if you feel like exploring your other options, there are a few: -* [Zettlr](https://www.zettlr.com) - Free, cross-platform, and open source -* [Mark Text](https://github.com/marktext/marktext) - Free, cross-platform, and open source -* [Remarkable](https://remarkableapp.github.io) - Linux and Windows, open source -* [NvChad](https://nvchad.github.io) for the `vi`/`vim` user and the `nvim` client. A lot of plugins are available to enhance the editor for markdown. See [this document](https://docs.rockylinux.org/books/nvchad/) for a nice set of installation instructions. -* [VS Code](https://code.visualstudio.com/) - A partially open source project from none other than Microsoft; VS Code is a lightweight and powerful editor available for Windows, Linux and MacOS. To contribute to this document project, you should get the following extensions: Git Graph, HTML Preview, HTML Snippets, Markdown All in One, Markdown Preview Enhanced, Markdown Preview Mermaid Support, and any more that catch your fancy. -### Markdown Tutorial +5. Create Pull Request -You can get a good feel for how to write Markdown files, by taking a look at [Mastering Markdown](https://guides.github.com/features/mastering-markdown/). This online resource will get you up-to-speed in no time. +So far you have been working in your own repository. Next you submit it to the documentation team to merge your version into the main version of the document. -### Admonitions and Translations +Click the green button that says Create Pull Request, which sends it to the RL documentation team for review. -Towards the end of 2021, we started translating our documents using [Crowdin](https://crowdin.com/). We need more translators for this effort, so if you would like to translate these documents into your language, please consider joining that effort. You can find more information by joining the conversation [here](https://chat.rockylinux.org/rocky-linux/channels/documentation). -It should be noted that admonitions are **NOT** required, but if you choose to use them, they should be formatted a little differently than the default. Here is the default way of creating an admonition: -``` -!!! type "optional additional title within double quotes" - Any number of other indented markdown elements. -``` -To make this work for our translators in Crowdin, however, we need to format it like this: -``` -!!! type "optional additional title within double quotes" - Any number of other indented markdown elements. -``` -The first line of the text detail for the admonition must have that extra line feed. Note that each example shows that there are 4 spaces before the actual text begins. When the page is rendered, the document will not have the extra line feed. Here's what the admonition above looks like: +6. Wait -!!! type "optional additional title within double quotes" +Once the RL team reviews your request, they will respond in one of three ways. - Any number of other indented markdown elements. -If you are reading this on GitHub, it will not display the admonition. You can see how it actually displays [here](https://docs.rockylinux.org/guides/contribute/). -## Author, Contributor, and Other Meta Content +* Accept and merge your PR +* Comment with feedback and ask for changes +* Deny your PR with explanation -We started to add specific meta to our documentation some time ago. The idea is to get the primary information in the meta. This is done in the source (English) documents. Here's an example of the meta information as it currently stands: +If you have to make changes, you will suddenly understand why you need a local repository. The team can [talk you through](https://chat.rockylinux.org/rocky-linux/channels/documentation) what to do next. In good news, it’s still fixable. + +Need more in-depth explanation? Here are the [same directions](https://docs.google.com/document/d/1Gkwxt3lsxC0HJdLB7YIEMBfPe0td1yVJZ8y5Bjs9oks/edit?usp=sharing) with more words and illustrations. + +Success? Welcome to the team, you are officially a Rocky Linux documentation contributor. Your profile will be added to the contributor list at the bottom of this document shortly. + + +### Become a frequent contributor + +For more than a word or two of occasional edits, we recommend that you [setup a local repository](add link to how to create a new document, once published) on your own machine. From there, you can revise documentation from your clone of the RL repository, Commit it to your online GitHub repository, and then create Pull Requests to merge with the main repository. + +Advanced users may wish to create a complete documentation server on your local Linux workstation or VM. We have guides to set that up with [Docker](https://docs.rockylinux.org/guides/contribute/rockydocs_web_dev/) or [LXD](https://docs.rockylinux.org/guides/contribute/mkdocs_lsyncd/). We also have a [fast documentation system](https://docs.rockylinux.org/guides/contribute/local_docs/) with special caveats if you are using Python on the same server. + + +### Submit a new document + +_Rocky Linux documentation includes guides, books, labs, and [gemstones](https://docs.rockylinux.org/gemstones/). Your original contributions are welcome in any of these categories._ + + +#### Meta + +Please include the following **meta** information at the top of all new documentation: -``` --- + title: Document title or the title that appears in the table of contents. (this can be overridden with `.pages` by editors if necessary.) + author: the author of the source (English) version of the document. + contributors: a comma separated list of contributors to the source document. + tested with: a comma separated list of versions example: 8.6, 9.0 + tags: + - displayable tags + - these are also searchable + - they are two space indented and start with a "-" as shown here + - generally, they should be one word + --- -``` -We ask those involved in translations to leave the meta as is in the document you are translating. We definitely **DO** want to acknowledge those involved in our translation efforts! That is what the all-contributors bot is for. If you scroll to the bottom of this page, you'll see a list of those who have contributed to the documentation project, even if it was just to change a word or phrase or fix an error. -If a translator runs into a word or phrase that does not translate well from the source document to their language, we ask them to go ahead and push a change to the source document through the normal Git processes. When they do this, they definitely *should* add their name to the "contributors:" meta! +#### Formatting + +To add more advanced elements to your Markdown-formatted document beyond text, visit the [formatting guide](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/). This covers Admonitions, Tables, Quotes, and more. + + +#### Contribute + +The process for [submitting original content](link to first time contributors guide, once published) is similar to updating an existing document from your local repository. Create a new document within your Markdown editor, Commit it to your GitHub repository, then submit a Pull Request to merge into the main branch of the repository. The documentation leads will decide where the new document will live. + -If you notice that your effort is not properly acknowledged in the all-contributors section, please let someone know in the [Mattermost channel](https://chat.rockylinux.org/rocky-linux/channels/documentation) so that we can fix it for you. Thank you to everyone who participates! +## Special Notes -## A Note About Links -When writing documentation you often need to use links. This can be links to other documents in the documentation (internal links), or links to external resources (external links). The format for all links within the documentation is square brackets around the descriptive name or label: [our site] followed by your link in parenthesis: (https://example.com). There's a third type of link which we will call a lab-based link. This is a link that does not resolve internally or externally, but refers to examples within your document. In October 22, we instituted a URL checking script within our GitHub PR test process. This script tests for failures of URLs and is great for keeping the documentation clean and accurate. It poses a special set of circumstances for lab-based URLs, however, as those lab-based URLs need to either fit within a set of already excluded names, or the author (you) would need to request that a new exclusion be added. An editor can also adjust your lab-based URL for you, or add an exclusion if they think it is warranted. +### Links + +Links can be internal (other docs within our domain), external (publicly hosted URLs), or lab-based (used as examples within your document). + +The format for all links within the documentation is square brackets around the descriptive name or label: + +[our site] followed by your link in parenthesis: (https://example.com) + +To help lab-based URLs pass our automatic URL checker, we have created a list of excluded names you may use. You may request that a new exclusion be added. An editor may adjust your lab-based URL, or add an exclusion if they think it is warranted. + -The following list of lab-based URLs can be used without requesting exceptions: * example.com * site.com @@ -102,66 +189,36 @@ The following list of lab-based URLs can be used without requesting exceptions: * your-server-hostname * localhost -## Using Git - -Like many other projects out there, Rocky Linux uses "git" to manage its code and files, including documentation files. This tutorial assumes a fundamental knowledge of Git and how it works. The second example also presupposes familiarity with the command line. - -The steps listed below will get you started. In the meantime (and until we inevitably develop our guide), you can learn Git in-depth with this [free Udacity course](https://www.udacity.com/course/version-control-with-git--ud123). If you don't have the time for that, here's [a shorter guide](https://blog.udacity.com/2015/06/a-beginners-git-github-tutorial.html). - -To submit your text, we ask that you create a GitHub account. When you are ready to submit your written documentation for approval, follow these easy steps: - -### With the GitHub GUI -You can complete almost all tasks from the web GUI on GitHub. Here's an example of adding a file you've created on your local machine to the Rocky Linux documentation GitHub repository. +### Translation -1. log in to your GitHub account. -2. Navigate to the Rocky Linux Documentation repository at [https://github.com/rocky-linux/documentation.git](https://github.com/rocky-linux/documentation.git) -3. You should be on the "Main" branch, so check the drop-down label down in the middle section to be sure you are. Your document might not ultimately end up in the "Main" branch, but admins will move it around to where it logically fits later. -On the right-hand side of the page, click the "Fork" button, which will create your copy of the documentation. -4. In the middle of the page on the forked copy, just to the left of the Green "Code" drop-down, is an "Add file" button. Click this and choose the "Upload files" option. -5. This will give you a way to either drag and drop files here or browse to them on your computer. Go ahead and use the method which you prefer. -6. Once the file is uploaded, the next thing you need to do is create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master. -Click on "Pull Request" in the upper-left of the screen. -7. Write a brief message in the "Write" section letting the administrators know what you've done. (New document, revision, suggested change, etc.,) then submit your change. -### From the Git Command-Line +#### CrowdIn -If you prefer to run Git locally on your machine, you can clone the Rocky Linux Documentation repository, make changes, and then commit changes afterward. To make things simple, execute steps 1-3 on from *With the GitHub GUI* above then: +We are adding to these docs in new languages at the speed of getting translators on board. Seeking contributors for this area especially. We use [CrowdIn](https://crowdin.com/) for updates. -1. Git clone the repository: `git clone https://github.com/your_fork_name/documentation.git` -2. Now, on your machine, add files to the directory. -Example: `mv /home/myname/help.md /home/myname/documentation/` -3. Next, run Git add for that file name. -Example: `git add help.md` -4. Now, run git commit for the changes you have made. -Example: `git commit -m "Added the help.md file"` -5. Next, push your changes to your forked repository: `git push https://github.com/your_fork_name/documentation main` -6. Next, we repeat steps 6 and 7 above: Create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master branch. Click on "Pull Request" in the upper-left of the screen -Once all of the above is complete, you wait for confirmation that GitHub successfully merged your request. (Or not, as the case may be.) +#### Translation and Meta content -## More Advanced Documents +Translators, if you find a word in the source document that does not translate well into your language, or an error that prevents a perfect translation, please fix that in the source document and make a Pull Request. In that case, please add yourself as a contributor in the meta content of that document. -If you are wanting to add more advanced elements in your document than just text (admonitions, tables, block quotes, etc.), [this document](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) will help you get there. +However, unless you modify the source document, please do not modify the meta content. -## Documentation Local Server +The place where we do want to acknowledge you is in the all-contributors section--at the bottom of this page. This is a list of everyone who has been part of this documentation project, whether creating content, spotting and fixing errors, or translating. Translators, you may add yourself (or [request to be added](https://chat.rockylinux.org/rocky-linux/channels/documentation)) here. We appreciate your contribution! -The advantage of having documentation running on a local server instance is that you get to see how your changes will look when they are taken to the live system. You can build a complete documentation system on your local Linux workstation or VM. This procedure isn't for everyone, and is definitely a more advanced topic. There are two documents that will get you to a nice, complete, and protected documentation system, using either Docker or LXD: -* Docker Version [here](https://docs.rockylinux.org/guides/contribute/rockydocs_web_dev/) -* LXD Version [here](https://docs.rockylinux.org/guides/contribute/mkdocs_lsyncd/) +## Communication channel -There is a third method that will get you up and running fast without either Docker or LXD, but read the caveats of this procedure carefully: +_For reporting issues, asking questions, getting support, and getting to know the documentarians._ -* Fast Documentation System [here](https://docs.rockylinux.org/guides/contribute/local_docs/) +For general questions about installing and using the distro, visit our [community forums](https://forums.rockylinux.org). For questions about the behind-the-scenes stuff like documentation, we have other channels. -## Keep Up With The Conversation -If you haven't already, join the conversation on the [Rocky Linux Mattermost Server](https://chat.rockylinux.org/rocky-linux/) and stay up-to-date with what is going on. Join the [~Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation), or any other channel you are interested in. We'd be glad to have you with us! +### Mattermost -## Contributors ✨ +To ask real-time questions, create a profile on the [Mattermost](https://mattermost.com/) server, then navigate to the Rocky Linux [General](https://chat.rockylinux.org/rocky-linux/channels/town-square) or [Documentation](https://chat.rockylinux.org/rocky-linux/channels/documentation) channel--or whichever channel seems appropriate to your question. You should get a response within hours if not right away. -Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): +Welcome aboard! Meet the rest of our awesome contributors below: ([emoji key](https://allcontributors.org/docs/en/emoji-key)): diff --git a/beginners.md b/beginners.md new file mode 100644 index 0000000000..17d4f92c6b --- /dev/null +++ b/beginners.md @@ -0,0 +1,113 @@ + + +## First time contributors guide + +_Everybody starts somewhere. If this is the first time you’ve contributed to open source documentation on GitHub, congratulations for taking this step. We can’t wait to see what you have to say!_ + + +### Git and GitHub + +Learn the basics of GitHub with this 12-minute [Beginner’s Guide to Git and GitHub](https://www.udacity.com/blog/2015/06/a-beginners-git-github-tutorial.html) from Udemy. + +You may not start out creating and managing repositories for Rocky Linux, but this [Hello World tutorial](https://docs.github.com/en/get-started/quickstart/hello-world) walks you through creating a GitHub account, learning the lingo, and understanding how repositories work. Focus on learning how to make and Commit updates to existing docs, and how to create a Pull Request. + + +### Markdown + +Markdown is an easy language that allows you to include formatting, code, and plain text in the same file. The first time you update a document, just follow the existing code. It won’t be long before you are ready to explore additional features. When the time comes, here’s are the basics. + + + +* [Basic Markdown](https://www.markdownguide.org/basic-syntax#code) +* [Extended Markdown](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) +* Some of the more [advanced formatting](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) options we use in our repository + + +### Local Repository Editor + +To create a local repository, first find and install a Markdown editor that works with your computer and operating system. Here are some options, but there are others. Use what you know. + +[ReText](https://github.com/retext-project/retext) - Free, cross-platform, and open source + +[Zettlr](https://www.zettlr.com/) - Free, cross-platform, and open source + +[Mark Text](https://github.com/marktext/marktext) - Free, cross-platform, and open source + +[Remarkable](https://remarkableapp.github.io/) - Linux and Windows, open source + +[NvChad](https://nvchad.com/) for the vi/vim user and the nvim client. A lot of plugins are available to enhance the editor for markdown. See [this document](https://docs.rockylinux.org/books/nvchad/) for a nice set of installation instructions. + +[VS Code](https://code.visualstudio.com/) - Partially open source, by Microsoft. VS Code is a lightweight and powerful editor available for Windows, Linux and MacOS. To contribute to this document project, you should get the following extensions: Git Graph, HTML Preview, HTML Snippets, Markdown All in One, Markdown Preview Enhanced, Markdown Preview Mermaid Support, and any more that catch your fancy. + +### Create a local repository + +Once you have a Markdown editor installed, follow instructions to connect it to your GitHub account and download your repository to your local machine. Every time you prepare to update a document, follow these steps to sync your local and online forks with the main branch to ensure you are working with the most current version: + +1. Within GitHub, sync your fork of the documentation repository with the main branch. +2. Follow your Markdown editor’s instructions to sync your current fork with your local machine. +3. Inside your Markdown editor, open the document you wish to modify. +4. Modify the document. +5. Save. +6. Commit your changes within your editor, which should sync your local repository with your online fork. +7. Within GitHub, find the updated document in your fork and create a Pull Request to merge it with the main document. + + +### Submit an update + +_Add a missing word, correct an error, clarify a confusing bit of text._ + +1. Start on the page you want to update. + +Click the “Edit” pencil in the upper right corner of the document you want to update. You will be taken to the original document on GitHub. + +The first time you contribute to the RL repository, you will be prompted with a green button to “**Fork** this **repository** and propose changes.” This creates a duplicate copy of the RL repository where you make your suggested edits. Simply click the green button and continue. + +2. Make your changes + +Follow the Markdown formatting. Perhaps there’s a missing word, or the link on line 21 needs to be fixed, for example. Make the necessary change. + +3. Propose changes + +At the bottom of the page, write a one line description in the title of the block entitled, “**Propose changes”**. It is helpful, but not necessary, to reference the file name found at the top of the doc. + +So if you updated a link within line 21 of the markdown text, you’d say something like, "Update README.md with correct links." + +**Note: Word your action in the present tense.** + +Then click Propose changes, which will **Commit** your changes to a complete document within your forked repository. + +4. Review changes + +Now you can look at what you’ve done, line by line. Did you miss anything? Back up to the previous page and correct it again (you’ll have to start over), then click Propose Changes again. + +Once the doc is the way you want it, click the green button that says Create Pull Request. This provides one more chance to double check your changes and confirm the doc is ready. + +5. Create Pull Request + +All of your work so far has been done in your own repository, with no opportunity to break the RL main repository. Next you submit it to the documentation team to merge your version into the main version of the document. + +Click the big green button that says Create Pull Request. Good news, you still haven’t broken anything, because now it goes to the RL documentation team for review. + +6. Wait + +Once the RL team gets your request, they will respond in one of three ways. + + + +* Accept and merge your PR +* Comment with feedback and ask for changes +* Deny your PR with explanation + +The last response is unlikely. We really want to include your perspective here! If you have to make changes, you’ll suddenly understand why you need a local repository. The team can [talk you through](https://chat.rockylinux.org/rocky-linux/channels/documentation) what to do next. In good news, it’s still fixable. Follow the comment section of that request to see what further information is requested. + +Otherwise, your request will be accepted and merged. Welcome to the team, you’re officially a contributor now! Look for your name to show up on the all-contributors list at the bottom of the Contributor Guide in a few days. diff --git a/createnew.md b/createnew.md new file mode 100644 index 0000000000..7c387c05ec --- /dev/null +++ b/createnew.md @@ -0,0 +1,49 @@ + + +## Create a new document + +_When you are ready to submit your original written documentation for approval, follow these easy steps:_ + + +### With the GitHub GUI + +You can complete almost all tasks from the web GUI on GitHub. Here's an example of adding a file you've created on your local machine to the Rocky Linux documentation GitHub repository. + + + +1. Login to your GitHub account. +2. Navigate to the Rocky Linux Documentation repository at [https://github.com/rocky-linux/documentation](https://github.com/rocky-linux/documentation). +3. You should be on the "Main" branch, so check the drop-down label down in the middle section to be sure you are. Your document might not ultimately end up in the "Main" branch, but admins will move it around to where it logically fits later. +4. On the right-hand side of the page, click the "Fork" button, which will create your copy of the documentation. +5. In the middle of the page on the forked copy, just to the left of the Green "Code" drop-down, is an "Add file" button. Click this and choose the "Upload files" option. +6. This will give you a way to either drag and drop files here or browse to them on your computer. Go ahead and use the method which you prefer. +7. Once the file is uploaded, the next thing you need to do is create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master. +8. Click on "Pull Request" in the upper-left of the screen. +9. Write a brief message in the "Write" section letting the administrators know what you've done. (New document, revision, suggested change, etc.,) then submit your change. + + +### From the Git Command-Line + +If you prefer to run Git locally on your machine, you can clone the [Rocky Linux Documentation](https://github.com/rocky-linux/documentation) repository, make changes, and then commit changes afterward. To make things simple, execute steps 1-3 on from With the GitHub GUI above, then: + + + +1. Git clone the repository: git clone https://github.com/your_fork_name/documentation.git +2. Now, on your machine, add files to the directory. +3. Example: mv /home/myname/help.md /home/myname/documentation/ +4. Next, run Git add for that file name. +5. Example: git add help.md +6. Now, run git commit for the changes you have made. +7. Example: git commit -m "Added the help.md file" +8. Next, push your changes to your forked repository: git push https://github.com/your_fork_name/documentation main +9. Next, repeat steps 6 and 7 above: Create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master branch. Click on "Pull Request" in the upper-left of the screen + +Watch for comments within the PR for requested revisions and clarifications. From 80f47e579767584d5efaaceb90d3d372ecfb935d Mon Sep 17 00:00:00 2001 From: wale soyinka Date: Tue, 20 Dec 2022 22:54:17 -0500 Subject: [PATCH 10/11] Update README.md --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 755395a736..0342fd5534 100644 --- a/README.md +++ b/README.md @@ -6,19 +6,18 @@ ## Introduction -_With Rocky Linux emerging as a major RHEL-compatible distribution, this is an exciting time in the open source community. Rocky’s [mission](https://rockylinux.org/community-charter/) is to provide companies a **stable foundation of open source software** for their enterprise and HPC needs. We are here to support that mission with excellent documentation._ +_With Rocky Linux emerging as a major RHEL-compatible distribution, this is an exciting time in the open source community. Rocky Linux’s [mission](https://rockylinux.org/community-charter/) is to provide companies and individuals with a **stable foundation of open source software** for their enterprise and HPC needs. We are here to support that mission with excellent documentation._ To us, excellent documentation hits these marks: - * Educate users how to admin this distribution and its associated programs. * Support users of all skill levels with manuals and troubleshooting guides to make the most of this distribution. * Apply a consistent standard across all related documents, for ease of reading and translation. * Keep documentation up to date (and error free) with current versions. -* Allow users to contribute Guides, Docs, Gemstones (scripts and favorite code snippets) and more, to enhance Rocky for fellow users. +* Allow users to contribute Guides, Docs, Gemstones (scripts and favorite code snippets) and more, to enhance Rocky Linux for fellow users. -We welcome anyone who wants to be part of this mission. No specific degree, years of experience, or company affiliation required. Be bold! You won’t break anything even if you fumble your first attempt. Promise. +We welcome anyone who wants to be part of this mission. No specific degree, years of experience, or company affiliation required. Be bold! We promise, you won’t break anything even if you fumble your first attempt. ## Technical requirements @@ -133,7 +132,7 @@ Please include the following **meta** information at the top of all new document --- -title: Document title or the title that appears in the table of contents. (this can be overridden with `.pages` by editors if necessary.) +title: Document title author: the author of the source (English) version of the document. From c0281fd9c9f3c47c8c3e7636021f8a69af92f988 Mon Sep 17 00:00:00 2001 From: wale soyinka Date: Tue, 20 Dec 2022 23:03:18 -0500 Subject: [PATCH 11/11] Update createnew.md --- createnew.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/createnew.md b/createnew.md index 7c387c05ec..b0520aa934 100644 --- a/createnew.md +++ b/createnew.md @@ -32,7 +32,7 @@ You can complete almost all tasks from the web GUI on GitHub. Here's an example ### From the Git Command-Line -If you prefer to run Git locally on your machine, you can clone the [Rocky Linux Documentation](https://github.com/rocky-linux/documentation) repository, make changes, and then commit changes afterward. To make things simple, execute steps 1-3 on from With the GitHub GUI above, then: +If you prefer to run Git locally on your machine, you can clone the [Rocky Linux Documentation](https://github.com/rocky-linux/documentation) repository, make changes, and then commit changes afterward. To make things simple, execute steps 1-3 using the **With the GitHub GUI** approach above, then: