From 86cde898092ccf7965c90f510d30cfdcb17c5d71 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 4 Jul 2018 10:03:05 +0100 Subject: [PATCH] docs: Requirements for filenames and commands Explain how to handle filenames and command names in documentation. Fixes #187. 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 ecd78bc1c1..b139df75f6 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -1,6 +1,7 @@ * [Introduction](#introduction) * [General requirements](#general-requirements) * [Notes](#notes) +* [Files and command names](#files-and-command-names) * [Code blocks](#code-blocks) # Introduction @@ -33,6 +34,24 @@ If there are multiple notes, bullets should be used: > > - I am important point *n*. +# Files and command names + +All filenames and command names should be rendered in a fixed-format font +using backticks: + +> Run the `foo` command to make it work. + +> Modify the `bar` option in file `/etc/baz/baz.conf`. + +Render any options that need to be specified to the command in the same manner: + +> Run `bar -axz --apply foo.yaml` to make the changes. + +For standard system commands, it is also acceptable to specify the name along +with the manual page section that documents the command in brackets: + +> The command to list files in a directory is called `ls(1)`. + # Code blocks This section lists requirements for displaying commands and command output.