diff options
| -rw-r--r-- | docs-style-en.xml | 14 |
1 files changed, 8 insertions, 6 deletions
diff --git a/docs-style-en.xml b/docs-style-en.xml index ee7c329..bec145b 100644 --- a/docs-style-en.xml +++ b/docs-style-en.xml @@ -1873,13 +1873,15 @@ Avoid overuse of admonitions. Keep admonitions short and effective by using only the most important material inside the admonition. Move any background material required to explain - the admonition statements outside the admonition. + the admonition statements outside the admonition. Use a short + but descriptive title for an admonition. Use title case for + the admonition title. </para> <example id="ex-misc-ineffective-admonition"> <title>Incorrect: Lengthy admonition</title> <para> <warning> - <title>Using <command>sfdisk</command></title> + <title>Use <command>sfdisk</command> to check input</title> <para> The <command>sfdisk</command> command accepts a script file as standard input to set up partitions on a hard @@ -1896,18 +1898,18 @@ <example id="ex-misc-good-admonition"> <title>Correct: Brief admonition</title> <para> - The <command>sfdisk</command> command accepts a script + The <command>sfdisk</command> command accepts a script file as standard input to set up partitions on a hard disk. Sometimes <command>sfdisk</command> will simply reject an erroneous input file. In other cases, it will use the input verbatim, writing an incorrect partition table to your disk. - <warning> - <title>Using <command>sfdisk</command></title> + <warning> + <title>Check Input</title> <para> Always use the <command>sfdisk -n</command> command to check your input file before writing to the disk. </para> - </warning> + </warning> </para> </example> <para> |