Skip to content

Commit e07cbbb

Browse files
author
daobrien
committed
Addresses #216 Using continuation characters.
This covers the initial aspect of this issue, which allows for the use or not of line continuation chars and PS2 prompts. Probably still need to sync with info in the DocBook Guide.
1 parent 0daec8d commit e07cbbb

1 file changed

Lines changed: 41 additions & 9 deletions

File tree

en-US/Design.xml

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -285,23 +285,55 @@ $ vi myFile.txt
285285

286286
</example>
287287
<para>
288-
If the commands are long, complex, or wrap over multiple lines, use the following design to help optimize clarity.
289-
If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit.
290-
</para>
288+
If the commands are long, complex, or wrap over multiple lines, two design options are available.
289+
</para>
290+
<itemizedlist>
291+
<listitem>
292+
<para>
293+
Use line continuation characters and the associated PS2 prompts.
294+
If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit.
295+
</para>
296+
</listitem>
297+
<listitem>
298+
<para>
299+
Use neither line continuation characters nor the associated PS2 prompts.
300+
</para>
301+
</listitem>
302+
</itemizedlist>
303+
<important>
304+
<para>
305+
Do not mix these two styles.
306+
Maintain the same style throughout your document.
307+
</para>
308+
</important>
309+
<para>
310+
You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required.
311+
This option is available for either of the two designs mentioned above.
312+
</para>
313+
291314
<example>
292-
<title>Documenting Long Commands</title>
315+
<title>Wrapping Long Commands with Continuation Characters</title>
316+
<para>
317+
This example uses both continuation characters and PS2 prompts.
318+
These indicators are always used together.
319+
</para>
293320

294321
<screen># tar --selinux -czvf config_files.tar.gz /etc/katello \
295322
> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \
296323
> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \
297324
> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \
298-
> /root/ssl–build /var/www/html/pub/* /var/lib/katello
325+
> /root/ssl–build /var/www/html/pub/* /var/lib/katello</screen>
326+
</example>
299327

300-
# cd /var/lib/katello
328+
<example><title>Wrapping Long Commands Without Continuation Characters</title>
329+
<para>
330+
This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help clarify long commands.
331+
</para>
332+
<screen># cd /var/lib/katello
301333

302-
# myCommand --option funky --color=true \
303-
> --config_file=&lt;replaceable&gt;/home/user/config.conf&lt;/replaceable&gt; \
304-
> --output_file=&lt;replaceable&gt;/home/user/output.txt&lt;/replaceable&gt;</screen>
334+
# myCommand --option funky --color=true
335+
--config_file=&lt;replaceable&gt;/home/user/config.conf&lt;/replaceable&gt;
336+
--output_file=&lt;replaceable&gt;/home/user/output.txt&lt;/replaceable&gt;</screen>
305337

306338
</example>
307339

0 commit comments

Comments
 (0)