From 33e264348d2db5af15fa3517128fc350747e07ab Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Tue, 1 Aug 2023 09:43:49 -0500 Subject: [PATCH] # Changes to rockydocs_formatting.md (#1383) * change title to "Document Formatting" * change the `.pages` file to properly alphabetize the list based on the new title * simplify some sentences * remove most passive voice * fix wording issues (Anna) * changed many (not all) of the uses of "we" to "you" --- docs/guides/contribute/.pages | 2 +- .../guides/contribute/rockydocs_formatting.md | 176 +++++++++--------- 2 files changed, 89 insertions(+), 89 deletions(-) diff --git a/docs/guides/contribute/.pages b/docs/guides/contribute/.pages index 6dc687bdca..ef7903e185 100644 --- a/docs/guides/contribute/.pages +++ b/docs/guides/contribute/.pages @@ -3,12 +3,12 @@ nav: - ... | README*.md - ... | beginners*.md - ... | createnew*.md + - ... | rockydocs_formatting*.md - ... | rockydocs_web_dev*.md - ... | rockydocs_webdev_v2*.md - ... | mkdocs_venv*.md - ... | mkdocs_lsyncd*.md - ... | local_docs*.md - ... | navigation*.md - - ... | rockydocs_formatting*.md - ... | style_guide*.md - ... diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index 7e9adea553..d90e71d6b5 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -1,5 +1,5 @@ --- -title: Rocky Docs Formatting +title: Document Formatting author: Steven Spencer contributors: tianci li, Ezequiel Bruni, Krista Burdine tags: @@ -7,11 +7,11 @@ tags: - formatting --- -# Rocky Docs Formatting - Introduction +# Introduction 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. If you feel that your document will benefit from special formatting, then this guide should help. +A document may or may not need to contain any of these elements. If you feel your document will benefit from special formatting, then this guide should help. !!! note "A Note About Headings" @@ -35,36 +35,36 @@ A document may or may not need to contain any of these elements. If you feel tha ## Admonitions -Admonitions are special visual "boxes" that allow you to call attention to important facts and highlight them in a way that makes them stand out from the rest of the text. Admonition types are as follows: +Admonitions are special visual "boxes" that allow you to call attention to important facts and highlight them. Following are types of admonitions: | type | Description | |-----------|-----------------------------------------------------------| -| note | renders a blue text box | -| abstract | renders a light blue text box | -| info | renders a blue-green text box | -| tip | renders a blue-green text box (icon slightly greener) | -| success | renders a green text box | -| question | renders a light green text box | -| warning | renders an orange text box | -| failure | renders a light red text box | -| danger | renders a red text box | -| bug | renders a red text box | -| example | renders a purple text box | -| quote | renders a grey text box | -| custom 1 | always renders a blue text box | -| custom 2 | uses a custom title within another type | - -There is no limit on the types of admonitions you can use as noted in custom 1 above. A custom title can be added to any of the other admonition types to get the colored box you want for a specific admonition, as noted in custom 2 above. +| 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 a 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 | + +Admonitions are limitless, as noted in custom 1 above. It is possible to 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. An admonition is always entered in this way: ``` -!!! admonition_type +!!! admonition_type "custom title if any" text of admonition ``` -The body text of the admonition must be indented four (4) spaces from the beginning margin. It's easy to see where that is in this case, because it will always line up under the first letter of the admonition type. The extra line between the title and body will not show up but is required for our translation engine (Crowdin) to function correctly. +The body text of the admonition must have a four (4) space indentation from the beginning margin. It is easy to see where that is because it will always line up under the first letter of the admonition type. The extra line between the title and body will not show up but our translation engine (Crowdin) needs these to function correctly. Here are examples of each admonition type, and how they will look in your document: @@ -106,35 +106,35 @@ Here are examples of each admonition type, and how they will look in your docume !!! custom - A custom 1 type. Here we've used "custom" as our admonition type. Again, this will always render in blue. + A custom 1 type. We have used "custom" as our admonition type. Again, this will always render in blue. !!! warning "custom title" - A custom 2 type. Here we've modified the "warning" admonition type with a custom header. Here's what that looks like: + A custom 2 type. We have modified the "warning" admonition type with a custom header. Here is what that looks like: ``` !!! warning "custom title" ``` -### Expandable Admonitions +### Expandable admonitions -If an admonition will have content that is very long, consider using an expandable admonition. This is treated the same way as a regular admonition but starts with three question marks, rather than three exclamation marks. All the other admonition rules apply. An expandable admonition looks like this: +If an admonition has very long content, consider an expandable admonition. It has the same characteristics of a regular admonition but starts with three question marks, rather than three exclamation marks. All the other admonition rules apply. An expandable admonition looks like this: ??? warning "Warning Content" - This is a warning, with not very much content. You'd want to use a regular admonition for this, but Hey, this is just an example! + This is a warning, with not very much content. You would want to use a regular admonition for this, but Hey, this is just an example! Which looks like this in your editor: ``` ??? warning "Warning Content" - This is a warning, with not very much content. You'd want to use a regular admonition for this, but Hey, this is just an example! + This is a warning, with not very much content. You would want to use a regular admonition for this, but Hey, this is just an example! ``` -## Tabbed Content within a Document +## Tabbed content within a document -Tabbed content is formatted in a similar way to admonitions. Instead of three exclamation marks or three question marks, it begins with three equal signs. All the admonition formatting (4 spaces, etc.) applies to this content. An example of this is where documentation 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 three 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: === "9.0" @@ -156,9 +156,9 @@ Which would look like this in your editor: The procedure for doing this in 8.6 ``` -Keep in mind that everything that falls inside of the section must continue to use the 4-space indentation until the section is completed. This is a very handy feature! +Remember that everything that falls inside of the section must continue to use the 4-space indentation until completion of the section. This is a very handy feature! -## Numbered Lists +## Numbered lists Numbered lists sound like they are easy to create and use, and once you get the hang of them, they really are. If you just have a single list of items with no complexity, then this sort of format works fine: @@ -176,65 +176,65 @@ Numbered lists sound like they are easy to create and use, and once you get the 3. Item 3 -If you need to add code blocks, multiple lines or even paragraphs of text to a numbered list, then the text should be indented with those same four (4) spaces that we used in the admonitions. +If you need to add code blocks, multiple lines or even paragraphs of text to a numbered list, then the text must have the same four (4) space indentation that you used in the admonitions. -You can't use your eyes to line them up under the numbered item, however, as this is one space off. If you are using a good markdown editor, you can set your tab value to four (4), which will make formatting everything a bit easier. +However, you cannot use your eyes to line them up under the numbered item because this is one space off. If you use a good markdown editor, you can set your tab value to four (4), which will make formatting everything a bit easier. -Here's an example of a multi-line numbered list with a code block thrown in for good measure: +Here is an example of a multi-line numbered list with a code block thrown in for good measure: -1. When dealing with numbered lists that are multi-line and include things like code blocks, use the space indentation to get what you want. +1. When dealing with multi-line numbered lists that include code blocks or other elements, use the space indentation to get what you want. - For example: this is indented four (4) spaces and represents a new paragraph of text. And here, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph: + For example: this has the four (4) space indentation and represents a new paragraph of text. In addition, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph: ``` dnf update ``` -2. Here's our second listed item. Because we used the indentation (above) it renders with the next sequence of numbering (in other words, 2), but if we had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what we want. +2. Here is our second listed item. Because you used the four (4) space indentation (above), it renders with the next sequence of numbering (2), but if you had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what you want. -And here's how that looks as raw text: +And here is how that looks as raw text: ```markdown -1. When dealing with numbered lists that are multi line and include things like code blocks, use the space indentation to get what you want. +1. When dealing with multi-line numbered lists that include code blocks or other elements, use the space indentation to get what you want. - For example: this is indented four (4) spaces and represents a new paragraph of text. And here, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph: + For example: this has the four (4) space indentation and represents a new paragraph of text. In addition, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph: ``` dnf update ``` -2. Here's our second listed item. Because we used the indentation (above) it renders with the next sequence of numbering (in other words, 2), but if we had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what we want. +2. Here is our second listed item. Because you used the four (4) space indentation (above), it renders with the next sequence of numbering (2), but if you had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what you want. ``` ## Tables -Tables help us to lay out command options, or in the above case, admonition types and descriptions. Here's how the table in the Admonitions section above is entered: +Tables help us to lay out command options, or in the above case, admonition types and descriptions. Here is how the table in the Admonitions section was entered: ``` | type | Description | |-----------|-----------------------------------------------------------| -| note | renders a blue text box | -| abstract | renders a light blue text box | -| info | renders a blue-green text box | -| tip | renders a blue-green text box (icon slightly greener) | -| success | renders a green text box | -| question | renders a light green text box | -| warning | renders an orange text box | -| failure | renders a light red text box | -| danger | renders a red text box | -| bug | renders a red text box | -| example | renders a purple text box | -| quote | renders a grey text box | -| custom 1 | always renders a blue text box | -| custom 2 | uses a custom title within another type | +| 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 a 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 | ``` -Note that it isn't necessary to have each column broken down by size (as we've done in the first part of the table), but it is certainly more readable in the markdown source file. It can get confusing when you string the items together, simply by breaking the columns with the pipe character "|" wherever the natural break would be, as you can see in the last two items of the table. +Note that it is not necessary to have each column broken down by size (as we have done in the first part of the table), but it is certainly more readable in the markdown source file. It can get confusing when you string the items together, simply by breaking the columns with the pipe character "|" wherever the natural break is, as you can see in the last item in the table. -## Block Quotes +## Block quotes -Block quotes are actually designed for quoting text from other sources to include in your documentation, but they don't have to be used that way. Some contributors use block quotes instead of tables, for instance, to list out some options. Examples of block quotes in markdown would be: +Block quotes are actually designed for quoting text from other sources to include in your documentation, but using them that way is not required. Some contributors use block quotes instead of tables, for instance, to list out some options. Examples of block quotes in markdown would be: ``` > **an item** - A description of that item @@ -242,16 +242,16 @@ Block quotes are actually designed for quoting text from other sources to includ > **another item** - Another description of that item ``` -To keep the lines from running together, the extra "spacing" line is necessary here. +The extra "spacing" line is necessary to keep the lines from running together. -That ends up looking like this when the page is rendered: +That ends up looking like this when the page displays: > **an item** - A description of that item > **another item** - Another description of an item -## Inline and Block-Level Code Blocks +## Inline and block-level code blocks -Our approach to using code blocks is pretty simple. If `your code` is short enough that you can (and want to) use it in a sentence like you just saw, use single backticks `, like so: +Our approach to the use of code blocks is pretty simple. If `your code` is short enough that you can (and want to) use it in a sentence like you just saw, use single backticks `: ``` A sentence with a `command of your choosing` in it. @@ -265,9 +265,9 @@ sudo dnf install the-kitchen-sink ``` ```` -The `bash` bit of that formatting is a non-essential code identifier but can help with syntax highlighting. Of course, if you're showcasing Python, PHP, Ruby, HTML, CSS, or any other kind of code, the "bash" should be changed to whatever language you're using. +The `bash` bit of that formatting is a non-essential code identifier but can help with syntax highlighting. If you showcase Python, PHP, Ruby, HTML, CSS, or any other kind of code, the "bash" will change to whatever language you use. -Incidentally, if you need to show a code block within a code block, just add one more backtick ` to the parent block, like so: +Incidentally, if you need to show a code block within a code block, just add one more backtick ` to the parent block: `````markdown ````markdown @@ -281,17 +281,17 @@ And yes, the code block you just saw used five backticks at the beginning and en ## Keyboard -Another way to add as much clarity to your documents as possible is to represent keys on the keyboard that must be entered in the correct manner. This is done with `key`. For instance, to represent that you need to hit the escape key in your document you would use `ESCCTRL + F4`. If keys need to be pressed simultaneously, add "simultaneously" or "at the same time" or some similar phrase to your instructions. Here's an example of a keyboard instruction in your editor: +Another way to add as much clarity to your documents as possible is to represent the entering of keys on a keyboard in the correct manner. Do this with `key`. For instance, to represent that you need to hit the escape key in your document you would use `ESCCTRL + F4`. If requiring the pressing of keys simultaneously, add "simultaneously" or "at the same time" or some similar phrase to your instructions. Here is an example of a keyboard instruction in your editor: ``` 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. ``` -And here's how that renders when displayed: +Here is how that renders when displayed: 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. -## Superscript, Subscript and Special Symbols +## Superscript, subscript and special symbols Superscript and subscript notation are not normal markdown, but are supported in Rocky Linux documentation via the HTML tags used for the same purpose. 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: @@ -299,7 +299,7 @@ Superscript and subscript notation are not normal markdown, but are supported in * copyright and trademark symbols, like ©, TM, or ™, ® * as notation for references, such as this1, this2 and this3 -Some of the special characters, such as © aren't normally superscript, while others such as ™, are. +Some of the special characters, such as © are not normally superscript, while others such as ™, are. Here is how all the above looks in your markdown code: @@ -308,14 +308,14 @@ Here is how all the above looks in your markdown code: * copyright and trademark symbols, like ©, TM or ™, ® * as notation for references, such as this1, this2 and this3 -Some of the special characters, such as © aren't normally superscript, while others such as ™, are. +Some of the special characters, such as © are not normally superscript, while others such as ™, are. ``` -As you can see, to force superscript we can use the supported HTML tags of ``. +As you can see, to force superscript you can use the supported HTML tags of ``. -Subscript is entered with the `` tags, and as noted earlier, isn't used nearly as much in writing. +Enter subscript with the `` tags, and as noted earlier, is not used nearly as much in writing. -### Superscript for References +### Superscript for references Some of you may feel the need to reference outside sources when writing documentation. If you only have a single source, you may wish to include it in your conclusion as a single link, but if you have multiples1, you can use superscript to note them in your text2 and then list them at the end of your document. Note that the positioning of references should come after the "Conclusion" section. @@ -329,7 +329,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's what that all looks like in your editor: +And here is what that all looks like in your editor: ``` 1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com) @@ -342,9 +342,9 @@ or ``` -## Grouping Different Formatting Types +## 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 instance, an admonition with a numbered list: !!! note @@ -364,7 +364,7 @@ Or you may have a numbered list, with an additional admonition: 1. This item is something very important - Here we are adding a keyboard command to the list item: + Here you are adding a keyboard command to the list item: Press ESC for no particular reason. @@ -376,9 +376,9 @@ Or you may have a numbered list, with an additional admonition: Things can get a little crazy with multiple elements within different formatting types! -As long as you keep track of the magic four (4) spaces to indent and separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. +If you keep track of the magic four (4) spaces to indent and separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. -You can even embed a table or block quote (literally any formatting item type) within another one. Here we have a numbered list, an admonition, a table and some block quote elements all bundled together: +You can even embed a table or block quote (literally any formatting item type) within another one. Here you have a numbered list, an admonition, a table and some block quote elements all bundled together: 1. Trying to keep up with everything that is going on in your document can be a real task when working with multiple elements. @@ -395,11 +395,11 @@ You can even embed a table or block quote (literally any formatting item type) w | red bull | tastes terrible - but it will keep you going! | | mountain dew | over hyped | - > **sugar** if caffeine isn't to your liking + > **sugar** if caffeine is not to your liking > **suffer** if all else fails, concentrate more -3. There are more examples, but the above should illustrate that everything can be nested within. Just remember the four (4) magic spaces. +3. Many examples exist, but the above illustrates that it is possible to nest everything within. Just remember the four (4) magic spaces. Here is what this example looks like in your editor: @@ -407,7 +407,7 @@ Here is what this example looks like in your editor: As long as you keep track of the magic four (4) spaces to separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. -You can even embed a table or block quote (literally any formatting item type) within another one. Here we have a numbered list, an admonition, a table and some block quote elements all bundled together: +You can even embed a table or block quote (literally any formatting item type) within another one. Here have a numbered list, an admonition, a table and some block quote elements all bundled together: 1. Trying to keep up with everything that is going on in your document can be a real task when working with multiple elements. @@ -424,16 +424,16 @@ You can even embed a table or block quote (literally any formatting item type) w | red bull | tastes terrible - but it will keep you going! | | mountain dew | over hyped | - > **sugar** if caffeine isn't to your liking + > **sugar** if caffeine is not to your liking > **suffer** if all else fails, concentrate more -3. There are more examples, but the above should illustrate that everything can be nested within. Just remember the four (4) magic spaces. +3. Many examples exist, but the above illustrates that it is possible to nest everything within. Just remember the four (4) magic spaces. ``` -## One Final Item - Comments +## One final item - comments -From time to time, you may want to add a comment to your markdown that will not display when rendered. There are a lot of reasons why you might want to do 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 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. 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: @@ -445,7 +445,7 @@ The best way to add a comment to your markdown is to use the square brackets "[] A comment should have a blank line before and after the comment. -## More Reading +## More reading * The Rocky Linux [how to contribute document](README.md)