docs: add documentation on some of tmux features

* How to turn off mouse to allow copy and paste. * How to display terminal history by keyboard. * How to launch multiple shell session inside tmux.
lablup · Jul 20, 2020 · d41d9d2 · d41d9d2
1 parent 1e8e8a0
commit d41d9d2
Show file tree

Hide file tree

Showing 2 changed files with 272 additions and 2 deletions.
diff --git a/docs/locale/ko/LC_MESSAGES/session_use/session_use.po b/docs/locale/ko/LC_MESSAGES/session_use/session_use.po
@@ -8,8 +8,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Backend.AI Console User Guide 19.09\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2020-06-13 23:19+0900\n"
-"PO-Revision-Date: 2020-06-13 23:21+0900\n"
+"POT-Creation-Date: 2020-07-20 23:55+0900\n"
+"PO-Revision-Date: 2020-07-20 23:58+0900\n"
 "Last-Translator: Jonghyun Park <jpark@lablup.com>\n"
 "Language: ko\n"
 "Language-Team: Lablup\n"
@@ -220,3 +220,189 @@ msgstr ""
 "세션 내부 폴더의 데이터는 연산 세션이 종료되는 순간 같이 삭제되므로, 계"
 "속 유지해야 하는 데이터라면 마운트 한 폴더에 옮기거나 처음부터 폴더에 업"
 "로드하는 것을 권합니다."
+
+#: ../../session_use/session_use.rst:127
+msgid "Advanced Web Terminal Usage"
+msgstr "웹 터미널 고급 사용법"
+
+#: ../../session_use/session_use.rst:129
+msgid ""
+"The web-based terminal we used above internally embed a utility called "
+"`tmux <https://github.com/tmux/tmux/wiki>`_. tmux is a terminal "
+"multiplexer that supports to open multiple shell windows within a single "
+"shell, so as to allow multiple programs to run in foreground "
+"simultaneously. If you want to take advantage of more powerful tmux "
+"features, you can refer to the official tmux documentation and other "
+"usage examples on the Internet."
+msgstr ""
+"위에서 사용 해보았던 웹 기반 터미널은 내부적으로 `tmux <https://github."
+"com/tmux/tmux/wiki>`_ 라는 유틸리티를 사용하고 있습니다. tmux는 하나의 "
+"쉘 내에서 여러 개의 창을 띄워 다중 작업 할 수 있도록 지원하는 terminal "
+"multiplexer로, 쉘이 닫히더라도 작업하던 내용을 보존할 수 있는 등 다양한 "
+"장점을 가지고 있습니다. 보다 강력한 터미널 기능을 활용하고 싶다면 tmux 공"
+"식 문서 및 기타 인터넷 상의 다양한 사용 예제를 참고하십시오."
+
+#: ../../session_use/session_use.rst:136
+msgid "Here we are introducing some simple but useful features."
+msgstr "여기서는 몇 가지 간단하지만 유용한 기능을 소개하겠습니다."
+
+#: ../../session_use/session_use.rst:138
+msgid "**Copy terminal contents**"
+msgstr "**터미널 내용 복사하기**"
+
+#: ../../session_use/session_use.rst:140
+msgid ""
+"tmux offers a number of useful features, but it's a bit confusing for "
+"first-time users. In particular, tmux has its own clipboard buffer, so "
+"when copying the contents of the terminal, you can suffer from the fact "
+"that it can be pasted only within tmux by default. Furthermore, it is "
+"difficult to expose user system's clipboard to tmux inside web browser, "
+"so when using tmux, the terminal contents cannot be copied and pasted to "
+"other programs of user's computer. The so-called ``Ctrl-C`` / ``Ctrl-V`` "
+"is not working."
+msgstr ""
+"tmux는 다양한 장점을 가지고 있지만 처음 접하는 사용자라면 다소 혼란스러"
+"운 부분도 있습니다. 특히, tmux는 자체 클립보드 버퍼를 가지고 있어 터미널"
+"의 내용을 복사할 경우 기본적으로 tmux 내에서만 붙여넣을 수 있다는 부분에"
+"서 어려움을 겪을 수 있습니다. 여기에 웹 기반 터미널에서는 사용자 시스템"
+"의 클립보드를 tmux에 노출시키기 어렵다는 한계가 더해져서, tmux 쉘을 사용"
+"하고 있는 상태에서는 마우스 드래그를 통해 터미널 내용을 복사한 후 사용자 "
+"컴퓨터의 다른 프로그램에 붙여넣을 수가 없습니다. 소위 말하는 ``Ctrl-"
+"C`` / ``Ctrl-V`` 가 작동하지 않는 것입니다."
+
+#: ../../session_use/session_use.rst:148
+msgid ""
+"If you need to copy and paste the terminal contents to your system's "
+"clipboard, you can temporarily turn off tmux's mouse support. First, "
+"press ``Ctrl-B`` key to enter tmux control mode. Then type ``:set -g "
+"mouse off`` and press ``Enter`` (note that you have to type the first "
+"colon as well). You can check what you are typing in the status bar at "
+"the bottom of the screen. Then drag the desired text from the terminal "
+"with the mouse and press the ``Ctrl-C`` or ``Cmd-C`` (in Mac) to copy "
+"them to the clipboard of the user's computer."
+msgstr ""
+"만약 터미널 내용을 사용자 시스템의 클립보드로 복사하여 붙여넣기를 할 필요"
+"가 있을 때는 잠시 tmux의 마우스 지원 설정을 끌 수 있습니다. 먼저 ``Ctrl-"
+"B`` 키를 눌러 tmux의 제어 모드로 진입합니다. 그 후 ``:set -g mouse off`` "
+"를 입력하고 엔터키를 누릅니다 (처음 콜론까지 입력해야 합니다). 입력하는 "
+"내용은 tmux 하단의 상태바에서 확인할 수 있습니다. 그 후 터미널에서 마우스"
+"로 원하는 텍스트를 드래그 하고 ``Ctrl-C`` 또는 ``Cmd-C`` 키를 누르면 사용"
+"자 컴퓨터의 클립보드에 해당 내용이 복사 됩니다."
+
+#: ../../session_use/session_use.rst:156
+msgid ""
+"With mouse support turned off, you cannot scroll through the mouse wheel "
+"to see the contents of the previous page from the terminal. In this "
+"case, you can turn on mouse support again. Press ``Ctrl-B``, and this "
+"time, type ``:set -g mouse on``. Now you can scroll mouse wheel to see "
+"the contents of the previous page."
+msgstr ""
+"마우스 지원을 끈 상태에서는 마우스 휠로 스크롤하여 터미널의 이전 페이지 "
+"내용을 확인할 수 없습니다. 이 때는 다시 마우스 지원을 켜면 됩니다. "
+"``Ctrl-B`` 를 누른 후 이번에는 ``:set -g mouse on`` 을 입력해봅시다. 이"
+"제 마우스 휠을 스크롤하여 이전 페이지의 내용을 볼 수 있게 되었습니다."
+
+#: ../../session_use/session_use.rst:161
+msgid ""
+"If you remember ``:set -g mouse off`` or ``:set -g mouse on`` after "
+"``Ctrl-B``, you can use the web terminal more conveniently."
+msgstr ""
+"이와 같이 ``Ctrl-B`` 후 ``:set -g mouse off`` 또는 ``:set -g mouse on`` "
+"을 기억하면 조금 더 편리하게 웹 터미널을 활용할 수 있습니다."
+
+#: ../../session_use/session_use.rst:165
+msgid ""
+"``Ctrl-B`` is tmux's default control mode key. If you set another "
+"control key by modifying ``.tmux.conf`` in user home directory, you "
+"should press the set key combination instead of ``Ctrl-B``."
+msgstr ""
+"``Ctrl-B`` 키는 tmux의 기본 제어 모드 키입니다. 만약 홈 디렉토리의 ``."
+"tmux.conf`` 를 수정하여 다른 제어 키를 설정한 경우에는, ``Ctrl-B`` 대신 "
+"설정된 키 조합을 눌러야 합니다."
+
+#: ../../session_use/session_use.rst:169
+msgid "**Checking the terminal history using keyboard**"
+msgstr "**키보드를 이용해 터미널 이전 내용 확인하기**"
+
+#: ../../session_use/session_use.rst:171
+msgid ""
+"There is also a way to copy the terminal contents and check the previous "
+"contents of the terminal simultaneously. It is to check the previous "
+"contents using the keyboard. Again, click ``Ctrl-B`` first, and then "
+"press the ``Page Up`` and/or ``Page Down`` keys. You can see that you "
+"navigate through the terminal's history with just keyboard. To exit "
+"search mode, just press the ``q`` key. With this method, you can check "
+"the contents of the terminal history even when the mouse support is "
+"turned off to allow copy and paste."
+msgstr ""
+"터미널 내용 복사도 하면서 터미널의 이전 내용도 확인하고 싶은 경우에도 방"
+"법이 있습니다. 바로 키보드를 이용해서 이전 내용을 확인하는 것입니다. 이번"
+"에도 ``Ctrl-B`` 를 먼저 클릭 해준 뒤 ``Page Up`` 과 ``Page Down`` 키를 눌"
+"러 봅시다. 키보드 만으로 터미널의 이전 내용을 탐색할 수 있다는 것을 확인"
+"할 수 있습니다. 탐색 모드에서 빠져 나오려면 ``q`` 키를 눌러주면 됩니다. "
+"이 방법을 이용하면 마우스 지원을 끈 상태에서도 터미널 이전 내용 확인이 가"
+"능합니다."
+
+#: ../../session_use/session_use.rst:179
+msgid "**Spawn multiple shells**"
+msgstr "**여러 개의 쉘 띄우기**"
+
+#: ../../session_use/session_use.rst:181
+msgid ""
+"The main advantage of tmux is that you can launch and use multiple "
+"shells in one terminal window. Since seeing is believing, let's press "
+"the ``Ctrl-B`` key and then the ``c``. You can see that the contents of "
+"the existing window disappeared and a new shell environment appeared. "
+"Then, did the previous window terminated? It's not like that. Let's "
+"press ``Ctrl-B`` and then ``w``. You can now see the list of shells "
+"currently open on tmux like following image. Here, the shell starting "
+"with ``0:`` is the shell environment you first saw, and the shell "
+"starting with ``1:`` is the one you just created. You can move between "
+"shells using the up/down keys. Place the cursor on the shell ``0:`` and "
+"press the Enter key to select it."
+msgstr ""
+"tmux의 가장 큰 장점은 하나의 터미널 창에서 여러 개의 쉘을 띄우고 사용할 "
+"수 있다는 점입니다. 백문이 불여일견이니 ``Ctrl-B`` 키를 누른 후 ``c`` 키"
+"를 이어서 눌러봅시다. 기존 창의 내용이 사라지고 새로운 쉘 환경이 뜬 것을 "
+"확인할 수 있습니다. 그러면 기존 창은 사라진 것일까요? 그렇지 않습니다. "
+"``Ctrl-B`` 누른 후 ``w`` 키를 눌러 봅시다. 다음과 같이 현재 tmux 상에서 "
+"열려 있는 쉘 리스트가 조회되는 것을 볼 수 있습니다. 여기서 ``0:`` 으로 시"
+"작하는 쉘이 처음 보던 쉘 환경이고, ``1:`` 로시작하는 쉘은 방금 새로 생성"
+"한 쉘입니다. 위/아래 방향 키를 이용해서 쉘 사이를 이동할 수 있습니다. "
+"``0:`` 번 쉘에 커서를 가져다 두고 엔터 키를 눌러 선택 해보겠습니다."
+
+#: ../../session_use/session_use.rst:195
+msgid ""
+"You can see the shell environment you saw first appears. In this way, "
+"you can use multiple shell environments within a web terminal. To exit "
+"or terminate the current shell, just enter ``exit`` command or press "
+"``Ctrl-B x`` key and then type ``y``."
+msgstr ""
+"처음 보았던 쉘 환경이 나타나는 것을 볼 수 있습니다. 이와 같은 방식으로 "
+"웹 터미널 내에서 여러 개의 쉘 환경을 띄워 두고 사용할 수 있습니다. 현재 "
+"쉘을 종료하려면 ``exit`` 명령을 입력하거나 ``Ctrl-B x`` 키를 누른 후 "
+"``y`` 를 입력하면 됩니다."
+
+#: ../../session_use/session_use.rst:200
+msgid "In summary:"
+msgstr "정리하면 다음과 같습니다:"
+
+#: ../../session_use/session_use.rst:202
+msgid "``Ctrl-B c``: create a new tmux shell"
+msgstr "``Ctrl-B c``: 새로운 tmux 쉘 생성"
+
+#: ../../session_use/session_use.rst:203
+msgid "``Ctrl-B w``: query current tmux shells and move around among them"
+msgstr "``Ctrl-B w``: tmux 쉘 조회 및 이동/선택"
+
+#: ../../session_use/session_use.rst:204
+msgid "``exit`` or ``Ctrl-B x``: terminate the current shell"
+msgstr "``exit`` 또는 ``Ctrl-B x``: 현재 tmux 쉘 종료"
+
+#: ../../session_use/session_use.rst:206
+msgid ""
+"Combining the above commands allows you to perform various tasks "
+"simultaneously on multiple shells."
+msgstr ""
+"위 명령을 조합하여 여러 개의 쉘에서 동시에 다양한 작업을 수행할 수 있습니"
+"다."
diff --git a/docs/session_use/session_use.rst b/docs/session_use/session_use.rst
@@ -121,3 +121,87 @@ To delete a specific session, tap the red trash icon. Since the data in the
 folder inside the compute session is deleted as soon as the compute session
 ends, it is recommended that you move the data to the mounted folder or upload
 it to the folder from the beginning if you want to keep it.
+
+
+Advanced Web Terminal Usage
+---------------------------
+
+The web-based terminal we used above internally embed a utility called `tmux
+<https://github.com/tmux/tmux/wiki>`_. tmux is a terminal multiplexer that
+supports to open multiple shell windows within a single shell, so as to allow
+multiple programs to run in foreground simultaneously. If you want to take
+advantage of more powerful tmux features, you can refer to the official tmux
+documentation and other usage examples on the Internet.
+
+Here we are introducing some simple but useful features.
+
+**Copy terminal contents**
+
+tmux offers a number of useful features, but it's a bit confusing for first-time
+users. In particular, tmux has its own clipboard buffer, so when copying the
+contents of the terminal, you can suffer from the fact that it can be pasted
+only within tmux by default. Furthermore, it is difficult to expose user
+system's clipboard to tmux inside web browser, so when using tmux, the terminal
+contents cannot be copied and pasted to other programs of user's computer. The
+so-called ``Ctrl-C`` / ``Ctrl-V`` is not working.
+
+If you need to copy and paste the terminal contents to your system's clipboard,
+you can temporarily turn off tmux's mouse support. First, press ``Ctrl-B`` key
+to enter tmux control mode. Then type ``:set -g mouse off`` and press ``Enter``
+(note that you have to type the first colon as well). You can check what you are
+typing in the status bar at the bottom of the screen. Then drag the desired text
+from the terminal with the mouse and press the ``Ctrl-C`` or ``Cmd-C`` (in Mac)
+to copy them to the clipboard of the user's computer.
+
+With mouse support turned off, you cannot scroll through the mouse wheel to see
+the contents of the previous page from the terminal. In this case, you can turn
+on mouse support again. Press ``Ctrl-B``, and this time, type ``:set -g mouse
+on``. Now you can scroll mouse wheel to see the contents of the previous page.
+
+If you remember ``:set -g mouse off`` or ``:set -g mouse on`` after ``Ctrl-B``,
+you can use the web terminal more conveniently.
+
+.. note::
+   ``Ctrl-B`` is tmux's default control mode key. If you set another control key
+   by modifying ``.tmux.conf`` in user home directory, you should press the set
+   key combination instead of ``Ctrl-B``.
+
+**Checking the terminal history using keyboard**
+
+There is also a way to copy the terminal contents and check the previous
+contents of the terminal simultaneously. It is to check the previous contents
+using the keyboard. Again, click ``Ctrl-B`` first, and then press the ``Page
+Up`` and/or ``Page Down`` keys. You can see that you navigate through the
+terminal's history with just keyboard. To exit search mode, just press the ``q``
+key. With this method, you can check the contents of the terminal history even
+when the mouse support is turned off to allow copy and paste.
+
+**Spawn multiple shells**
+
+The main advantage of tmux is that you can launch and use multiple shells in one
+terminal window. Since seeing is believing, let's press the ``Ctrl-B`` key and
+then the ``c``. You can see that the contents of the existing window disappeared
+and a new shell environment appeared. Then, did the previous window terminated?
+It's not like that. Let's press ``Ctrl-B`` and then ``w``. You can now see the
+list of shells currently open on tmux like following image. Here, the shell
+starting with ``0:`` is the shell environment you first saw, and the shell
+starting with ``1:`` is the one you just created. You can move between shells
+using the up/down keys. Place the cursor on the shell ``0:`` and press the Enter
+key to select it.
+
+.. image:: tmux_multi_session_pane.png
+   :alt: tmux's multiple session management
+
+You can see the shell environment you saw first appears. In this way, you can
+use multiple shell environments within a web terminal. To exit or terminate the
+current shell, just enter ``exit`` command or press ``Ctrl-B x`` key and then
+type ``y``.
+
+In summary:
+
+- ``Ctrl-B c``: create a new tmux shell
+- ``Ctrl-B w``: query current tmux shells and move around among them
+- ``exit`` or ``Ctrl-B x``: terminate the current shell
+
+Combining the above commands allows you to perform various tasks simultaneously
+on multiple shells.