/
roxterm.1.xml.in
913 lines (873 loc) · 31.8 KB
/
roxterm.1.xml.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!--
Process this file with an XSLT processor: `xsltproc -''-nonet \
/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
roxterm.xml'. A manual page <package>.<section> will be generated. You
may view the manual page with: nroff -man <package>.<section> | less'.
A typical entry in a Makefile or Makefile.am is:
DB2MAN=/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
XP=xsltproc -''-nonet
manpage.1: manpage.dbk
$(XP) $(DB2MAN) $<
The xsltproc binary is found in the xsltproc package. The
XSL files are in docbook-xsl. Please remember that if you
create the nroff version in one of the debian/rules file
targets (such as build), you will need to include xsltproc
and docbook-xsl in your Build-Depends control field.
-->
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "<firstname>Tony</firstname>">
<!ENTITY dhsurname "<surname>Houghton</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "<date>01 April 2013</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection "<manvolnum>1</manvolnum>">
<!ENTITY dhemail "<email>h@realh.co.uk</email>">
<!ENTITY dhusername "Tony Houghton">
<!ENTITY dhucpackage "<refentrytitle>roxterm</refentrytitle>">
<!ENTITY dhpackage "roxterm">
<!ENTITY product "ROXTerm">
<!ENTITY debian "<productname>Debian</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
]>
<refentry lang="en">
<refentryinfo>
<address>
&dhemail;
</address>
<author>
<contrib>Developer</contrib>
&dhfirstname; &dhsurname;
</author>
<copyright>
<year>2005-2020</year>
<holder>&dhusername;</holder>
</copyright>
&dhdate;
</refentryinfo>
<refmeta>
&dhucpackage;
&dhsection;
<refmiscinfo class="source">&product;</refmiscinfo>
<refmiscinfo class="version">@VERSION@</refmiscinfo>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>terminal emulator</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&dhpackage;</command>
<arg><option>-?</option> | <option>--help</option></arg>
<arg><option>--help-all</option></arg>
<arg><option>--help-gtk</option></arg>
<arg><option>-u</option> | <option>--usage</option></arg>
<arg><option>--geometry=<replaceable>GEOM</replaceable></option>
| <option>-g <replaceable>GEOM</replaceable></option></arg>
<arg><option>--appdir=<replaceable>DIR</replaceable></option></arg>
<arg><option>--profile=<replaceable>PROFILE</replaceable></option> |
<option>-p <replaceable>PROFILE</replaceable></option></arg>
<arg><option>--colour-scheme=<replaceable>SCHEME</replaceable></option> |
<option>--color-scheme=<replaceable>SCHEME</replaceable></option> |
<option>-c <replaceable>SCHEME</replaceable></option></arg>
<arg><option>--shortcut-scheme=<replaceable>SCHEME</replaceable></option>
| <option>-s <replaceable>SCHEME</replaceable></option></arg>
<arg><option>--separate</option></arg>
<arg><option>--replace</option></arg>
<arg><option>--fork</option></arg>
<arg><option>--hold</option></arg>
<arg><option>--atexit=<replaceable>ACTION</replaceable></option></arg>
<arg><option>--directory=<replaceable>DIR</replaceable></option> |
<option>-d <replaceable>DIR</replaceable></option></arg>
<arg><option>--show-menubar</option></arg>
<arg><option>--hide-menubar</option></arg>
<arg><option>--maximise</option> | <option>-m</option></arg>
<arg><option>--fullscreen</option> | <option>-f</option></arg>
<arg><option>--borderless</option> | <option>-b</option></arg>
<arg><option>--disable-sm</option></arg>
<arg><option>--tab</option></arg>
<arg><option>--zoom=<replaceable>ZOOM</replaceable></option> |
<option>-z <replaceable>ZOOM</replaceable></option></arg>
<arg><option>--title=<replaceable>TITLE</replaceable></option> |
<option>-T <replaceable>TITLE</replaceable></option></arg>
<arg><option>--tab-name=<replaceable>NAME</replaceable></option> |
<option>-n <replaceable>NAME</replaceable></option></arg>
<arg><option>--role=<replaceable>ROLE</replaceable></option></arg>
<arg><option>--session=<replaceable>SESSION</replaceable></option></arg>
<arg><option>--display=<replaceable>DISPLAY</replaceable></option></arg>
<arg><option>--execute <replaceable>COMMAND</replaceable></option> |
<option>-e <replaceable>COMMAND</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
ROXTerm is a terminal emulator.
It provides features similar to gnome-terminal.
It is based on the same VTE library,
which implements a virtual terminal emulator.
</para>
<para>
The original design goals of ROXTerm were twofold.
A small memory footprint and a quick start-up time.
This was realised by not using the Gnome libraries
and by moving the configuration GUI to a separate applet.
However, thanks to all the features it has acquired
over the years, ROXTerm can now be accused of bloat.
But it is now very configurable indeed.
It is aimed at "power" users who make heavy use of terminals
and who wish to have fine control over the many options.
</para>
<para>
ROXTerm still supports the ROX desktop application layout
it was named after. It can also be installed in a conventional
manner for use in other desktop environments.
Both X11 and Wayland are supported.
</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<para>ROXTerm follows the usual &gnu; command line syntax.
Both long options starting with two dashes (`-') and
short single dash options are provided.
Here follows a summary of options.
</para>
<variablelist>
<varlistentry>
<term><option>-?</option>
<option>--help</option>
</term>
<listitem>
<para>Show a list of ROXTerm options.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--help-gtk</option>
</term>
<listitem>
<para>Show only the GTK+ options.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--help-all</option>
</term>
<listitem>
<para>Show all options.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--usage</option>
</term>
<listitem>
<para>Show a brief summary of usage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d <replaceable>DIRECTORY</replaceable></option>
<option>--directory=<replaceable>DIRECTORY</replaceable></option>
</term>
<listitem>
<para>Run shell/command in
<replaceable>DIRECTORY</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-g <replaceable>COLUMNSxROWS[+X+Y]</replaceable></option>
<option>--geometry=<replaceable>COLUMNSxROWS[+X+Y]</replaceable></option>
</term>
<listitem>
<para>Set the size of the terminal window.
Optionally a position may be given as well.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--appdir=<replaceable>DIR</replaceable></option>
</term>
<listitem>
<para>Application directory when run as a ROX app.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-menubar</option>
<option>--hide-menubar</option>
</term>
<listitem>
<para>Whether to show or hide the menubar, overriding the profile.
The default is to show it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--maximise</option>
<option>-m</option>
</term>
<listitem>
<para>Make initial terminal window take up the whole screen, but
keep the window frame decorations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--fullscreen</option>
<option>-f</option>
</term>
<listitem>
<para>Make initial terminal window take up the whole screen with
no window furniture.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--borderless</option>
<option>-b</option>
</term>
<listitem>
<para>Disable window decorations like title bar, resize controls
and frame border, if the window manager supports this.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tab</option>
</term>
<listitem>
<para>If possible open the new terminal in an existing window rather
than open a new window. If used in conjunction with
<option>-T</option>/<option>--title</option> the tab will be placed
in an existing window with the same title template if one exists.
This option overrides <option>--zoom</option> and
<option>--fullscreen</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--zoom=<replaceable>ZOOM</replaceable></option>
<option>-z <replaceable>ZOOM</replaceable></option>
</term>
<listitem>
<para>Scale terminal's font by a factor of ZOOM (1.0 is normal
size).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p <replaceable>PROFILE</replaceable></option>
<option>--profile=<replaceable>PROFILE</replaceable></option>
</term>
<listitem>
<para>Use the named profile.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c <replaceable>SCHEME</replaceable></option>
<option>--colour-scheme=<replaceable>SCHEME</replaceable></option>
<option>--color-scheme=<replaceable>SCHEME</replaceable></option>
</term>
<listitem>
<para>Use the named colour scheme.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s <replaceable>SCHEME</replaceable></option>
<option>--shortcut-scheme=<replaceable>SCHEME</replaceable></option>
</term>
<listitem>
<para>Use the named keyboard shortcut scheme.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--title=<replaceable>TITLE</replaceable></option>
<option>-T <replaceable>TITLE</replaceable></option>
</term>
<listitem>
<para>Set window title template. May include "%s" which
is substituted with the full contents of the tab's label,
"%n" which is substituted by the number of tabs,
and "%t" which is substituted by the current tab number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tab-name=<replaceable>NAME</replaceable></option>
<option>-n <replaceable>NAME</replaceable></option>
</term>
<listitem>
<para>Set tab name as displayed in its label. May include "%s" which
is substituted with the window title string set by the terminal,
"%n" which is substituted by the number of tabs,
and "%t" which is substituted by the current tab number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--separate</option>
</term>
<listitem>
<para>Use a separate process for this terminal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--fork</option>
</term>
<listitem>
<para>Always fork into the background. Usually the first instance
stays in the foreground and subsequent invocations return once they
have asked the master instance to handle their command. This option
causes the master instance to fork itself into the background; the
foreground process returns once the master is ready to handle further
commands.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--atexit=<replaceable>ACTION</replaceable></option>
</term>
<listitem>
<para>What should be done with the tab after the shell
command exits. Choose one of: close, hold, respawn, ask.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--hold</option>
</term>
<listitem>
<para>An alias for --atexit=hold. Keep the tab open.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--replace</option>
</term>
<listitem>
<para>Replace any existing instance as ROXTerm D-BUS service
provider.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--role=<replaceable>ROLE</replaceable></option>
</term>
<listitem>
<para>Set the WM_WINDOW_ROLE property on the window.
This can be used to uniquely identify a window across sessions,
or in selecting configuration resources by window managers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--session=<replaceable>SESSION</replaceable></option>
</term>
<listitem>
<para>Restore the named user session.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--display=<replaceable>DISPLAY</replaceable></option>
</term>
<listitem>
<para>The named X server display to use. If you use roxterm
on multiple different displays on the same system
then you need to use the --separate option as well.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>
<option>--execute</option>
</term>
<listitem>
<para>
Execute remainder of the command line inside
the terminal. This must be the final option.
If there is only one following argument,
it is parsed in case it is a command
with space-separated arguments that
was passed to roxterm in quotes.
If there is more than one argument
they are treated as a command and
arguments without parsing.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SETUP</title>
<para>
D-Bus is a messaging system which ROXTerm uses
to connect terminals with its configure tool.
ROXTerm uses the "session" bus, which should
be started along with your desktop environment.
Current versions of ROX, GNOME and KDE/Plasma
session managers all launch D-Bus.
If you use some other session/desktop/window manager,
which doesn't launch D-Bus, you need to start it yourself.
Insert something like this near the start of your
.xinitrc or .xsession:
</para>
<programlisting>
if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
eval `dbus-launch --sh-syntax --exit-with-session`
export DBUS_SESSION_BUS_ADDRESS
fi
</programlisting>
<para>
This setup provides a way to map an arbitrary
number of profiles onto configuration filenames.
</para>
</refsect1>
<refsect1>
<title>TABS</title>
<para>
Each window can contain a number of tabs,
each with its own terminal.
The tab bar is always shown by default,
even if there is only one tab,
to avoid resizing inconsistencies,
but this is configurable.
</para>
<para>
If you experience a problem with tab labels shrinking,
after dragging tabs so that they only have room to display '...',
then make sure the pointer is over the body
of a terminal when you drop a dragged tab,
not over the tab bar area.
</para>
</refsect1>
<refsect1>
<title>MENUS</title>
<para>
When the menu bar is hidden,
the popup menu duplicates the same items as in the menu bar.
This gives you full access to all the functions
with the menu bar hidden.
The menu bar is effectively redundant,
but provided to make ROXTerm appear
more straightforward for first-time users.
It can be turned on and off for a particular window
or more permanently by using the configuration manager.
</para>
<para>
The popup menu also allows email and web addresses
to be opened in external applications,
if such an address is highlighted
by the pointer being over it.
</para>
</refsect1>
<refsect1>
<title>URI HIGHLIGHTING</title>
<para>
When the pointer is over an address
that ROXTerm recognises as a URI
(typically a web URL or email address)
it is highlighted by underlining and
a change of pointer shape.
You can open the address either by right-clicking on it
and choosing Open... in the menu
or by holding Ctrl and left-clicking.
The applications used to handle these
addresses may be set with the configuration tool,
otherwise it will try to find a suitable default.
</para>
<para>
Also, by holding down the Ctrl key,
you can drag a URI to pass it to another application
which is willing to accept it as a URI or text.
Dragging it into the same window it came from
pastes the address back in.
</para>
<para>
If the pointer is over the server address portion of a URL
it only highlights the address, but not the filename.
Move the pointer over the filename to get the whole URL.
Similarly, you can highlight an email address with
or without a leading mailto:.
</para>
<para>
SSH URI and hostname matching is supported.
URIs including a path name can only be copied to the clipboard.
In the absence of a pathname, ROXTerm can
also start a ssh session to the described host.
Plain hostnames are also matched,
but only if they start with "ssh",
or end with ".local" or ".lan".
</para>
</refsect1>
<refsect1>
<title>DRAG AND DROP</title>
<para>
You can drag items onto terminal windows.
Text objects are fed to the terminal as if typed.
Files and URIs have their location fed in
rather than the object's contents.
Graphical files can also be dragged onto the
appropriate area of the configuration manager
to set terminal background images.
Hold down the Ctrl key while dragging
a highlighted URI, to allow the address
to be dragged to another application.
</para>
<para>
You can now drag tabs by their labels
to reorder them within a window
or to move them to another ROXTerm window
or, by dropping them outside a ROXTerm window,
move tabs to new windows of their own.
Use mouse button 3 (the right button)
to move an unselected tab without selecting it.
Button 2 is a shortcut to paste the contents
of the clipboard as the tab's name.
</para>
</refsect1>
<refsect1>
<title>SESSIONS</title>
<para>
User sessions can be saved under a name. Click Save Session...
in the File menu. A session preserves the current state
windows and tabs, but not their textual content.
A session can be restored with the --session option.
It will be restored by the default if it is named 'Default'.
Leaving the field blank is equivalent to 'Default'.
</para>
</refsect1>
<refsect1>
<title>Configuration</title>
<para>
Configuration is based on named profiles,
so you can save different sets of options
and switch between them quickly.
There are profiles for general options,
colour schemes and keyboard shortcuts.
Colour Schemes and Profiles apply to
one tab at a time, but Keyboard Shortcuts
apply to all tabs in the same window.
New windows and tabs inherit settings
from the window/tab they were opened from.
</para>
<para>
The Preferences menu allows you to select the current profile.
Open the configuration manager to edit the current profile
or colour scheme, or to manage all settings.
In the configuration manager you can select
one of the four types of option groups and edit,
copy, delete or rename them.
The item with the selected radio button
is the default for new terminals.
</para>
</refsect1>
<refsect1>
<title>KEYBOARD SHORTCUTS</title>
<para>
ROXTerm allows the keyboard shortcut profiles
to be edited in a text editor, either via the
Configuration Manager or from a terminal's
menu (Preferences submenu). The action names
correspond to the localised labels used in
the menu items. The new shortcuts should
automatically be reloaded when you save the
file. Alternatively, selecting a scheme in the
Preferences menu now forces it to be reloaded.
The default file for keyboard shortcuts is:
</para>
<programlisting>
~/.config/roxterm.sourceforge.net/Shortcuts/Default.
</programlisting>
<para>
The default keyboard shortcuts are:
</para>
<programlisting>
Ctrl+Shift+N New Window
Ctrl+Shift+T New Tab
Ctrl+Shift+Q Close Window
Ctrl+Shift+W Close Tab
Ctrl+PageUp Previous Tab
Ctrl+PageDown Next Tab
Ctrl+Shift+A Select All
Ctrl+Shift+C Copy
Ctrl+Shift+V Paste
Ctrl+Shift+M Show Menubar
Ctrl+plus Zoom In
Ctrl+minus Zoom Out
Ctrl+0 Normal Size
F11 Full Screen
Ctrl+Shift+B Borderless
Shift+Up Scroll Up One Line
Shift+Down Scroll Down One Line
F1 Show Manual
Ctrl+Shift+Y Copy & Paste
Ctrl+Shift+F Find...
Ctrl+Shift+I Find Next
Ctrl+Shift+P Find Previous
</programlisting>
<para>
In addition, tabs can be selected by
<keycombo action='simul'>
<keycap>Alt</keycap>
<keycap>1</keycap>
</keycombo>,
where 1 is to be replaced by the tab number.
This can be disabled in the profile.
</para>
</refsect1>
<refsect1>
<title>Configuration Management</title>
<para>
Run the configuration manager by selecting "Configure..."
in ROXTerm's menu or run <command>roxterm-config</command>.
</para>
<para>
Configuration files can be swapped with other users.
Each profile, colour scheme and keyboard shortcut scheme
consists of a single file. Saving a file in the
appropriate directory will create a profile
with the same name as the file.
</para>
<para>
Locations for files follow the XDG Base Directory specification.
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
${XDG_CONFIG_HOME}/roxterm.sourceforge.net,
defaulting to ~/.config/roxterm.sourceforge.net.
</para>
</listitem>
<listitem>
<para>
${XDG_CONFIG_DIRS}/roxtem.sourceforge.net,
defaulting to /etc/xdg/roxtem.sourceforge.net.
</para>
</listitem>
<listitem>
<para>
ROXTerm/Config for ROX users,
or ${datadir}/roxterm/Config for others.
${datadir} is usually /usr/share for packages
or /usr/local/share when compiled from source.
</para>
</listitem>
</orderedlist>
<para>
Within any or each of those locations,
profiles are saved in a "Profiles" subdirectory,
colour schemes in "Colours" and
keyboard shortcut schemes in "Shortcuts".
A file called "Global" contains miscellaneous options,
which don't fall into the above categories,
including the default profile for new terminals.
</para>
</refsect1>
<refsect1>
<title>ADVANCED</title>
<para>
ROXTerm terminals can be configured from applications and
scripts via D-BUS. For this purpose there are three methods.
They require an ID code to target a specific terminal.
Each roxterm's ID can be read from the environment variable
ROXTERM_ID in the shell or application running in it.
The D-Bus object path is "net.sf.roxterm.Options" and
the D-Bus interface is "/net/sf/roxterm/Options".
The methods are:
</para>
<programlisting>
SetProfile("id", "profile_name")
</programlisting>
<para>
Ask the terminal to use the named profile.
Note that any other tabs in the same window
will be updated to the same new profile.
All tabs in one window must have the same profile, so
that their font size and terminal size remain consistent.
</para>
<programlisting>
SetColourScheme("id", "scheme_name")
</programlisting>
<para>
Ask the terminal to use the named colour scheme.
Tabs sharing the same window may have different
colour schemes from each other.
</para>
<programlisting>
SetShortcutScheme("id", "scheme_name")
</programlisting>
<para>
Ask the terminal to use the named keyboard shortcut scheme.
Tabs sharing the same window must also
share the same shortcut scheme.
</para>
<para>
Example using dbus-send in a shell script:
</para>
<programlisting>
dbus-send --session /net/sf/roxterm/Options \
net.sf.roxterm.Options.SetColourScheme \
string:$ROXTERM_ID string:GTK
</programlisting>
<para>
You may also send D-Bus signals to change
individual options within a named profile
or colour scheme using the methods StringOption,
IntOption (also used for boolean options)
and FloatOption. All terminals using the
named profile or colour scheme are affected,
but only temporarily. The options are not saved
for new terminals. The methods all take 3 arguments:
</para>
<itemizedlist>
<listitem>
<para>
Full profile name, including a prefix of
"Profiles/" or "Colours/"
</para>
</listitem>
<listitem>
<para>
Option name
</para>
</listitem>
<listitem>
<para>
Value
</para>
</listitem>
</itemizedlist>
<para>
To see which option names you can use, check the config files, from which the types can be deduced. Example using dbus-send in a shell script:
</para>
<programlisting>
dbus-send --session /net/sf/roxterm/Options \
net.sf.roxterm.Options.StringOption \
string:Colours/GTK string:background 'string:#ffffff'
</programlisting>
<para>
A third possible use is to notify roxterm that a profile, colour scheme or shortcuts scheme has been changed by an external program and all terminals using that profile etc need to reload it:
</para>
<programlisting>
OptionsChanged("family_name", "profile_name")
</programlisting>
<para>
where family_name is one of "Profiles", "Colours"
or "Shortcuts". For example:
</para>
<programlisting>
dbus-send --session /net/sf/roxterm/Options \
net.sf.roxterm.Options.OptionsChanged \
string:Profiles string:Default
</programlisting>
</refsect1>
<refsect1>
<title>ENVIRONMENT</title>
<para>
The following environment variables are set or used by roxterm:
</para>
<variablelist>
<varlistentry>
<term>COLORTERM</term>
<listitem>
<para>This is set to "truecolor" by VTE if the window supports
16 million colors.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EDITOR</term>
<listitem>
<para>The name of the editor.
Defaults to "gedit", "kate", "gvim", "emacs",
whichever appears first in PATH.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LANG</term>
<listitem>
<para>
The language of the help URI. This defaults to "en".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ROXTERM_ID</term>
<listitem>
<para>
The unique identity of the roxterm D-Bus instance.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ROXTERM_NUM</term>
<listitem>
<para>
The number of toplevel windows which are managed
by this roxterm process.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ROXTERM_PID</term>
<listitem>
<para>
The process identifier of roxterm.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TERM</term>
<listitem>
<para>
The name of the terminfo description, which is xterm-256color.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>VTE_VERSION</term>
<listitem>
<para>The version number of the VTE library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WINDOWID</term>
<listitem>
<para>
The decimal X Window ID of the toplevel roxterm window. Only
supported in an X environment.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>XDG_CONFIG_HOME</term>
<listitem>
<para>
Where to save roxterm sessions. Defaults to ~/.config.
Sessions are saved under
$XDG_CONFIG_HOME/roxterm.sourceforge.net/UserSessions/.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<filename>file://@CMAKE_INSTALL_FULL_DOCDIR@/en/index.html</filename>
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>This manual page was written by &dhusername; &dhemail;.
Permission is granted to copy, distribute and/or modify this document
under the terms of the &gnu; General Public License, Version 2 or any
later version published by the Free Software Foundation.
</para>
<para>
On Debian systems, the complete text of the GNU General Public
License can be found in /usr/share/common-licenses/GPL.
</para>
</refsect1>
</refentry>