Skip to content

Updates for dashes, terminal, omitting output #618

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 25, 2024
Merged

Updates for dashes, terminal, omitting output #618

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
07658aa
Updates for dashes, terminal, omitting output
julian-cable Sep 20, 2024
f541ca1
add shell prompt example
julian-cable Sep 20, 2024
2d6a7ff
Further updates
julian-cable Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions en-US/C.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,16 +332,23 @@

</varlistentry>
<varlistentry id="command-line">
<term>command line, command prompt, command-line</term>
<term>command line, command-line, command prompt</term>
<listitem>
<para>
For an explanation of how to use these terms, refer to the appropriate entries in <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
Use "command line" to refer to the place where commands are entered.
Use "command line" as a noun, and use "command-line" as an adjective.
</para>
<para>
For more details about how to use these terms, refer to the appropriate entries in <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
<para>
Refer also to <xref linkend="shell-prompt"/> and to <xref linkend="terminal"/>.
</para>

</listitem>

Expand Down
16 changes: 3 additions & 13 deletions en-US/D.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,9 @@
<term>dash</term>
<listitem>
<para>
In technical publications, <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon> recommends not to use em&nbsp;dashes. Use a colon or other suitable punctuation.
En&nbsp;dashes are used to show a range.
Refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=punctuation-dashes"><citetitle>Dashes</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
Use a dash to show a range, such as for page numbers, letters, pages, or dates.
Otherwise, do not use dashes in technical content.
Instead, use other punctuation marks, such as commas, parentheses, or a colon.
</para>

</listitem>
Expand Down
37 changes: 35 additions & 2 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -529,16 +529,49 @@ The ARN in the preceding output is different on your system.
For the sake of brevity, do not show all output to the user in all cases, but only those parts of any output that are relevant to the context that is described.
Where output is not included, place a marker to show that information is purposely excluded.
When shortening the output, use a consistent notation.
Red&nbsp;Hat uses the <emphasis>...output omitted...</emphasis> notation, starting and ending with an ellipsis, and highlighted in italics.
For omitting horizontal lines of output, Red&nbsp;Hat uses the <emphasis>...output&nbsp;omitted...</emphasis> notation, starting and ending with an ellipsis, and highlighted in italics.
</para>

<example><title>Notation for Excluding Part of Output</title>
<example><title>Notation for Omitting Horizontal Output</title>
<screen>[student@workstation image]$ podman build --layers=false -t nexus .
STEP 1: FROM ubi8/ubi:8.3
Getting image source signatures
<emphasis>...output omitted...</emphasis>
STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest</screen>

</example>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few thoughts here - I'm a little hesitant to share definitive guidelines about using the ellipsis notation for vertical columns of output, because that's not yet official guidance. (So far, it's only implemented in one course, and not documented elsewhere.)

Although, depending on the timing of this style guide release, maybe it can be official guidance by then. Perhaps we could qualify the guideline here, or frame it more clearly as an example, or another kind of omission or notation to consider? Or omit it? What do you think?

The following example is very useful, but also quite lengthy. We might consider cutting several lines of output (and using the correct notation, of course! =)


<para>
For omitting vertical columns of output, use a consistent notation such as an ellipsis (...).
</para>

<example><title>Notation for Omitting Vertical Output</title>
<screen>[user@host ~]$ <userinput>oc get csv</userinput>
NAME DISPLAY ...
barbican-operator.v1.0.0 Barbican Operator ...
cinder-operator.v1.0.0 Cinder Operator ...
designate-operator.v1.0.0 Designate Operator ...
glance-operator.v1.0.0 Glance Operator ...
heat-operator.v1.0.0 Heat Operator ...
horizon-operator.v1.0.0 Horizon Operator ...
<emphasis>...output omitted...</emphasis></screen>
<!-- infra-operator.v1.0.0 OpenStack Infra ...
ironic-operator.v1.0.0 Ironic Operator ...
keystone-operator.v1.0.0 Keystone Operator ...
manila-operator.v1.0.0 Manila Operator ...
mariadb-operator.v1.0.0 MariaDB Operator ...
metallb-operator.v4.14.0-202407091409 MetalLB Operator ...
neutron-operator.v1.0.0 Neutron Operator ...
nova-operator.v1.0.0 Nova Operator ...
octavia-operator.v1.0.0 Octavia Operator ...
openstack-ansibleee-operator.v1.0.0 OpenStackAnsibleEE ...
openstack-baremetal-operator.v1.0.0 OpenStack Baremetal Operator ...
openstack-operator.v1.0.0 OpenStack ...
ovn-operator.v1.0.0 OVN Operator ...
placement-operator.v1.0.0 Placement Operator ...
rabbitmq-cluster-operator.v0.0.1 RabbitMQ Cluster Operator ...
swift-operator.v1.0.0 Swift operator ...
telemetry-operator.v1.0.0 Telemetry Operator ... -->
</example>

</section>
Expand Down
4 changes: 2 additions & 2 deletions en-US/E.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
</listitem>

</varlistentry>
<varlistentry id="emdash">
<!-- <varlistentry id="emdash">
<term>emdash</term>
<listitem>
<para>
Expand All @@ -55,7 +55,7 @@

</listitem>

</varlistentry>
</varlistentry> -->

<varlistentry id="enter">
<term>enter</term>
Expand Down
8 changes: 7 additions & 1 deletion en-US/S.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,13 @@
<term>shell prompt</term>
<listitem>
<para>
Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt", "terminal", or "shell".
Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt" or "shell".
</para>
<para>
For example, "If you enter your username and password correctly, then you log in and get a shell prompt."
</para>
<para>
Refer also to <xref linkend="command-line"/> and to <xref linkend="terminal"/>.
</para>

</listitem>
Expand Down
22 changes: 19 additions & 3 deletions en-US/T.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,16 +92,32 @@
<term>terminal</term>
<listitem>
<para>
<emphasis>n.</emphasis> Do not use to describe where to type commands. Use "command line" instead.
<emphasis>n.</emphasis> Use "terminal" to refer to a text-based interface where typed instructions are entered, or to refer to a session of this type.
</para>
<para>
<para>
For example, "Open a terminal and log in to your OpenShift cluster", or "The exercise file captures any error messages from your terminal".
</para>
<para>
<!-- Use "command line" or "shell prompt" instead to refer to the prompt where commands are entered. -->
Use "command line" instead to refer to the place where commands are entered.
</para>
<para>
For example, "Copy the command from the web console and paste it on the command line."
</para>
<para>
Refer also to <xref linkend="command-line"/> and to <xref linkend="shell-prompt"/>.
</para>
<!-- <para>
<emphasis>n.</emphasis> Do not use to describe where to type commands. Use "command line" instead.
</para> -->
<!-- <para>
For more information, refer to the Word Usage section of <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
</para> -->

</listitem>

Expand Down