From 205c6eaba8a2275c8a952e4e61cb149e2ee05ffa Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 21 Nov 2018 10:29:26 +0000 Subject: [PATCH 1/3] docs: Add missing article Add an article to make the notes section read more naturally in the doc requirements doc. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index 59db98897d..0b31f841b9 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -18,7 +18,7 @@ Containers](https://github.com/kata-containers) project. # Notes Important information that is not part of the main document flow should be -added as a Note in bold with all content contained within block quote: +added as a Note in bold with all content contained within a block quote: > **Note:** This is areally important point! > From e81421a5d1e87feea1f5e3c778e7453994def744 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 21 Nov 2018 10:31:11 +0000 Subject: [PATCH 2/3] docs: Remove bang from code block Remove the `!` from the `echo` in the code example in the doc requirements doc. The current code is in fact invalid as the shell will try to interpret the exclamation mark as it is a reserved word. Rather than escaping it in the example, just remove it. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index 0b31f841b9..5a911a141a 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -72,7 +72,7 @@ utility. ```bash $ echo "Hi - I am some bash code" $ sudo docker run -ti busybox true - $ [ $? -eq 0 ] && echo "success!" + $ [ $? -eq 0 ] && echo "success" ``` ``` From ce85eb2ccd3143979463cdcd6edccf946e1a5f5a Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 21 Nov 2018 10:33:37 +0000 Subject: [PATCH 3/3] docs: Add warnings to doc requirements doc Document how other admonitions such as warnings and hints should be handled. Fixes #307. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index 5a911a141a..29f32405f6 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -1,6 +1,7 @@ * [Introduction](#introduction) * [General requirements](#general-requirements) * [Notes](#notes) +* [Warnings and other admonitions](#warnings-and-other-admonitions) * [Files and command names](#files-and-command-names) * [Code blocks](#code-blocks) * [Images](#images) @@ -35,6 +36,24 @@ If there are multiple notes, bullets should be used: > > - I am important point *n*. +# Warnings and other admonitions + +Use the same approach as for [notes](#notes). For example: + +> **Warning:** Running this command assumes you understand the risks of doing so. + +Other examples: + +> **Warnings:** +> +> - Do not unplug your computer! +> - Always read the label. +> - Do not pass go. Do not collect $200. + +> **Tip:** Read the manual page for further information on available options. + +> **Hint:** Look behind you! + # Files and command names All filenames and command names should be rendered in a fixed-format font