Skip to content

Commit

Permalink
Merge pull request #468 from StyleGuides/daobrien/365-remove-docbook-…
Browse files Browse the repository at this point in the history
…refs

Closes #365 Remove DocBook references.
  • Loading branch information
mweetman-redhat authored Feb 13, 2023
2 parents 10d5f01 + 3d9f18c commit 847e124
Showing 1 changed file with 6 additions and 3 deletions.
9 changes: 6 additions & 3 deletions en-US/Design.xml
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@
Gerunds should be avoided elsewhere.
See <xref linkend="sentence-structure" />.
</para>
</important>
</important>
<formalpara>
<title>File Names, Commands, and Related Terms</title>
<para>
Expand Down Expand Up @@ -567,10 +567,13 @@ $ vi myFile.txt
To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result.
</para>
<para>
For example, do not refer to <command>cat</command> or <command>vi</command> if you need to tell readers to "view the <filename>my-script</filename> file". If you need to tell readers to edit a file and add or remove content, write "Edit the <filename>my-script</filename> file and add the following content:" and then include the required content in a &lt;screen&gt; block. Use &lt;code&gt; tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change.
For example, do not refer to <command>cat</command> or <command>vi</command> if you need to tell readers to "view the <filename>my-script</filename> file".
If you need to tell readers to edit a file and add or remove content, write "Edit the <filename>my-script</filename> file and add the following content:" and then include the required content in a code block and highlight the text to change.
Include some surrounding text in the file for context.
Do not use line numbers as a reference point because they can change.
</para>
<para>
If the file to edit is empty or does not exist, do not use &lt;code&gt; tags to highlight any content to add.
If the file to edit is empty or does not exist, do not highlight any content to add.
</para>
<para>
You can also use <systemitem>here</systemitem> documents to describe how to create a file with required content. The syntax of <systemitem>here</systemitem> documents varies by system, shell, language, and so on. The following example creates the <filename>my-script</filename> file in the current directory, with the example content.
Expand Down

0 comments on commit 847e124

Please sign in to comment.