From dc9256cb23014bfc5f31605eed5fec52ad4073dd Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Wed, 4 Dec 2024 12:29:41 -0600 Subject: [PATCH] Formatting changes: * add in a section for "Forcing line breaks" * add in a section for "Non-displaying characters" * replace some passive voice phrasing with active voice * some additional sentence simplification * other minor corrections --- .../guides/contribute/rockydocs_formatting.md | 143 ++++++++++++------ 1 file changed, 99 insertions(+), 44 deletions(-) diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index ff1955c439..ddc0121613 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -11,7 +11,7 @@ tags: This guide highlights our more advanced formatting options, including admonitions, numbered lists, tables, and more. -A document may or may not need to contain any of these elements. However, if you feel your document will benefit from special formatting, this guide should help. +A document might or might not need to contain any of these elements. However, if you feel your document will benefit from special formatting, this guide should help. !!! note "A Note About Headings" @@ -45,22 +45,22 @@ A document may or may not need to contain any of these elements. However, if you Admonitions are special visual "boxes" that allow you to call attention to important facts and highlight them. The following are types of admonitions: -| type | Description | -|-----------|-----------------------------------------------------------| -| note | displays text in a blue box | -| abstract | displays text in a light blue box | -| info | displays text in a blue-green box | -| tip | displays text in a blue-green box (icon slightly greener) | -| success | displays text in a green box | -| question | displays text in a light green box | -| warning | displays text in an orange box | -| failure | displays text in a light red box | -| danger | displays text in a red box | -| bug | displays text in a red box | -| example | displays text in a purple box | -| quote | displays text in a grey box | -| custom ^1^ | always displays text in a blue box | -| custom ^2^ | displays text in the color of the box of the chosen type | +| type | Description | +|------------|-----------------------------------------------------------| +| note | displays text in a blue box | +| abstract | displays text in a light blue box | +| info | displays text in a blue-green box | +| tip | displays text in a blue-green box (icon slightly greener) | +| success | displays text in a green box | +| question | displays text in a light green box | +| warning | displays text in an orange box | +| failure | displays text in a light red box | +| danger | displays text in a red box | +| bug | displays text in a red box | +| example | displays text in a purple box | +| quote | displays text in a gray box | +| custom ^1^ | always displays text in a blue box | +| custom ^2^ | displays text in the color of the box of the chosen type | As noted in custom 1 above, admonitions are limitless. Add a custom title to any admonition type to get the box color you want for a specific admonition, as noted in custom 2 above. @@ -142,7 +142,7 @@ Which looks like this in your editor: ## Tabbed content within a document -Formatting tabbed content is similar to admonitions. Instead of three exclamation marks or question marks, it begins with three equal signs. All the admonition formatting (4 spaces and so on) applies to this content. For example, a document might need a different procedure for a different Rocky Linux version. When using tabbed content for versions, the most recent release of Rocky Linux should come first. At the time of this writing, that was 9.0: +Formatting tabbed content is similar to admonitions. Instead of three exclamation marks or question marks, it begins with three equal signs. All the admonition formatting (4 spaces and so on) applies to this content. For example, a document might need a different procedure for a different Rocky Linux version. When using tabbed content for versions, the most recent release of Rocky Linux should come first. At the time of this writing, it was 9.0: === "9.0" @@ -216,25 +216,25 @@ And here is how that looks as raw text: ## Tables -In the above case, tables help us lay out command options or admonition types and descriptions. Here is how the table in the Admonitions section was entered: +In the above case, tables help us lay out command options or admonition types and descriptions. This shows the entry of the table in the Admonitions section: ```text -| type | Description | -|-----------|-----------------------------------------------------------| -| note | displays text in a blue box | -| abstract | displays text in a light blue box | -| info | displays text in a blue-green box | -| tip | displays text in a blue-green box (icon slightly greener) | -| success | displays text in a green box | -| question | displays text in a light green box | -| warning | displays text in an orange box | -| failure | displays text in a light red box | -| danger | displays text in a red box | -| bug | displays text in a red box | -| example | displays text in a purple box | -| quote | displays text in a grey box | -| custom^1^ | always displays text in a blue box | -| custom^2^ | displays text in a box with the color of the chosen type | +| type | Description | +|-----------|------------------------------------------------------------| +| note | displays text in a blue box | +| abstract | displays text in a light blue box | +| info | displays text in a blue-green box | +| tip | displays text in a blue-green box (icon slightly greener) | +| success | displays text in a green box | +| question | displays text in a light green box | +| warning | displays text in an orange box | +| failure | displays text in a light red box | +| danger | displays text in a red box | +| bug | displays text in a red box | +| example | displays text in a purple box | +| quote | displays text in a gray box | +| custom^1^ | always displays text in a blue box | +| custom^2^ | displays text in a box with the color of the chosen type | ``` @@ -242,7 +242,7 @@ Note that it is not necessary to have each column broken down by size (as we hav ## Block quotes -Block quotes are designed for quoting text from other sources to include in your documentation. Examples of block quotes in markdown would be: +Block quotes are for quoting text from other sources to include in your documentation. Examples of block quotes in markdown would be: ```text > **an item** - A description of that item @@ -290,7 +290,7 @@ sudo dnf install the-kitchen-sink ```` ````` -And yes, the code block you just saw used five backticks at the beginning and end to make it render correctly. +Yes, the code block you just saw used five backticks at the beginning and end to make it render correctly. ### Suppressing the displayed prompt and automatic line feed @@ -326,6 +326,13 @@ A list of accepted keyboard commands [in this document](https://facelessuser.git These keyboard shortcuts are always entered in lower case except where a custom keyboard command is used within the quotes. +## Forcing line breaks + +There are times when a simple ++enter++ on the keyboard will not give you a new line in markdown. This sometimes occurs when bulleted items use a lot of formatting characters. You may want to add a line break to better format text as well. In cases like these, you need to add two spaces to the end of the line where you want a new line. Since spaces will not be visible in some markdown editors, this example shows the spaces being entered: + +* **A bullet item with extra formatting** ++space+space++ +* **Another item** + ## Superscript, subscript and special symbols Superscript and subscript notation are supported in Rocky Linux documentation by use of the `^` for superscript and `~` for subscript. Superscript places text entered between the tags slightly above the normal text, while subscript places the text slightly below. Superscript is by far the more commonly used of these two in writing. Some special characters already appear in superscript without adding the tags, but you can also combine the tag to change the orientation of those characters as seen with the copyright symbol below. You can use superscript to: @@ -354,7 +361,7 @@ Enter subscript by surrounding your text with the `~` tag (H~2~0 is `H~2~0`) and Some of you may need to reference outside sources when writing documentation. If you only have a single source, you can include it in your conclusion as a single link, but if you have multiples^1^, you can use superscript to note them in your text^2^ and then list them at the end of your document. Note that the positioning of references should come after the "Conclusion" section. -Following the conclusion, you can have your notations in a numbered list to match the superscript or enter them as links. Both examples are shown here: +Following the conclusion, you can have your notations in a numbered list to match the superscript or enter them as links. Shown here are both examples: 1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com) 2. "Using Superscript In Text" by Sam B. Supersecret [https://site2.com](https://site2.com) @@ -364,7 +371,7 @@ or [1](https://site1.com) "How Multiples Are Used In Text" by Wordy W. McWords [2](https://site2.com) "Using Superscript In Text" by Sam B. Supersecret -And here is what that all looks like in your editor: +Here is what that all looks like in your editor: ```text 1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com) @@ -379,17 +386,17 @@ or ## Highlighting text -Another possible way to enhance documentation is with ==highlighting==. Highlighting is handled by surrounding the text with `==`. +Another possible way to enhance documentation is with ==highlighting==. You can use highlighting by surrounding the text with `==`. This looks like this in your editor: ```bash -Another possible way to enhance documentation is with ==highlighting==. Highlighting is handled by surrounding the text with `==`. +Another possible way to enhance documentation is with ==highlighting==. You can use highlighting by surrounding the text with `==`. ``` ## Grouping different formatting types -Rocky documentation offers some elegant formatting options when combining multiple elements within another element. For instance, an admonition with a numbered list: +Rocky documentation offers some elegant formatting options when combining multiple elements within another element. For example, an admonition with a numbered list: !!! note @@ -476,9 +483,57 @@ You can even embed a table or block quote (literally any formatting item type) w 3. Many examples exist, but the above illustrates that it is possible to nest everything within. Just remember the four (4) magic spaces. ``` +## Non-displaying characters + +There are some characters in markdown that will not display properly. Sometimes it is because these characters are HTML or other tag types (links for example). There might be times when writing documentation that you **need** to display these characters to get your point across. The rule to display these characters is to escape them. Here is a table of these non-displaying characters followed by a code block that shows the table code. + +| symbol | description | +|-------------|---------------------------------------------------| +| \\ | backslash (used for escaping) | +| \` | backtick (used for code blocks) | +| \* | asterisk (used for bullets) | +| \_ | underscore | +| \{ \} | curly braces | +| \[ \] | brackets (used for link titles) | +| < > | angle brackets (used for direct HTML) | +| \( \) | parentheses (used for link content) | +| \# | pound sign (used for markdown headers) | +| | | pipe (used in tables) | +| + | plus sign (used in tables) | +| - | minus sign or hyphen (used in tables and bullets) | +| ! | exclamation (used in admonitions and tables) | + +That table in code is: + +```table +| symbol | description | +|-------------|---------------------------------------------------| +| \\ | backslash (used for escaping) | +| \` | backtick (used for code blocks) | +| \* | asterisk (used for bullets) | +| \_ | underscore | +| \{ \} | curly braces | +| \[ \] | brackets (used for link titles) | +| < > | angle brackets (used for direct HTML) | +| \( \) | parentheses (used for link content) | +| \# | pound sign (used for markdown headers) | +| | | pipe (used in tables) | +| + | plus sign (used in tables) | +| - | minus sign or hyphen (used in tables and bullets) | +| ! | exclamation (used in admonitions and tables) | +``` + +The last code shows that certain characters require their HTML character code if used in a table. + +In actual text, you would escape the character. For example, `\|` will show the pipe symbol, `\>` will show the angle bracket symbol, `\+` will show the plus sign, `\-` will show the minus sign, and `\!` will show the exclamation mark. + +You can see that if we get rid of the back ticks in this sentence: + +In actual text, you would escape the character. For example, \| will show the pipe symbol, \> will show the angle bracket symbol, \+ will show the plus sign, \- will show the minus sign, and \! will show the exclamation mark. + ## One final item - comments -From time to time, you may want to add a comment to your markdown that will not display when rendered. Many reasons exist for this. For instance, if you want to add a placeholder for something that will be added later, you could use a comment to mark your spot. +From time to time, you might want to add a comment to your markdown that will not display when rendered. Many reasons exist for this. If you want to add a placeholder for something that you are adding later, you could use a comment to mark your spot. The best way to add a comment to your markdown is to use the square brackets "[]" around two forward slashes "//" followed by a colon and the content. This would look like this: @@ -504,6 +559,6 @@ A comment should have a blank line before and after the comment. Document formatting with headings, admonitions, tables, numbered lists, and block quotes can add clarity to your document. When using admonitions, take care to pick the correct type. This can make it easier to visually see the importance of the particular admonition. -You do not *have* to use advanced formatting options. Overuse of special elements can add clutter where none is needed. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. +You do not *have* to use advanced formatting options. Overuse of special elements can add clutter. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. Lastly, to make formatting easier, consider changing your markdown editor's TAB value to four (4) spaces.