From dd8539f581bd3541b9476ac3a62ad6627426e098 Mon Sep 17 00:00:00 2001 From: Michael Lazar Date: Thu, 11 Feb 2016 18:20:35 -0800 Subject: [PATCH] Simplified a bunch of the language in the readme. --- CONTROLS.rst | 65 ++++++++++++++++++++++++ README.rst | 135 +++++++++++--------------------------------------- rtv/config.py | 2 +- rtv/docs.py | 9 +--- 4 files changed, 98 insertions(+), 113 deletions(-) create mode 100644 CONTROLS.rst diff --git a/CONTROLS.rst b/CONTROLS.rst new file mode 100644 index 0000000..8ffcea8 --- /dev/null +++ b/CONTROLS.rst @@ -0,0 +1,65 @@ +======== +Controls +======== + +-------------- +Basic Commands +-------------- + +:``j``/``k`` or ``▲``/``▼``: Move the cursor up/down +:``m``/``n`` or ``PgUp``/``PgDn``: Jump to the previous/next page +:``1-5``: Toggle post order (*hot*, *top*, *rising*, *new*, *controversial*) +:``r`` or ``F5``: Refresh page content +:``u``: Log in or switch accounts +:``?``: Show the help screen +:``q``/``Q``: Quit/Force quit + +---------------------- +Authenticated Commands +---------------------- + +Some actions require that you be logged in to your reddit account. +You can log in by pressing ``u`` while inside of the program. +Once you are logged in your username will appear in the top-right corner of the screen. + +:``a``/``z``: Upvote/downvote +:``c``: Compose a new post or comment +:``e``: Edit an existing post or comment +:``d``: Delete an existing post or comment +:``i``: Display new messages prompt +:``s``: View a list of subscribed subreddits + +-------------- +Subreddit Mode +-------------- + +In subreddit mode you can browse through the top submissions on either the front page or a specific subreddit. + +:``l`` or ``►``: Enter the selected submission +:``o`` or ``ENTER``: Open the submission link with your web browser +:``/``: Open a prompt to switch subreddits +:``f``: Open a prompt to search the current subreddit + +The ``/`` prompt accepts subreddits in the following formats + +* ``/r/python`` +* ``/r/python/new`` +* ``/r/python+linux`` supports multireddits +* ``/r/front`` will redirect to the front page +* ``/r/me`` will display your submissions + +--------------- +Submission Mode +--------------- + +In submission mode you can view the self text for a submission and browse comments. + +:``h`` or ``◄``: Return to the subreddit +:``o`` or ``ENTER``: Open the comment permalink with your web browser +:``SPACE``: Fold the selected comment, or load additional comments + +------- +Key Map +------- + +.. image:: http://i.imgur.com/xDUQ03C.png \ No newline at end of file diff --git a/README.rst b/README.rst index 2d668ee..0c744f6 100644 --- a/README.rst +++ b/README.rst @@ -2,8 +2,8 @@ RTV: Reddit Terminal Viewer =========================== -RTV is an application that allows you to view and interact with reddit from your terminal. -It is compatible with *most* terminal emulators on Linux and OSX. +RTV allows you to view and interact with reddit from your terminal. +It's compatible with *most* terminal emulators on Linux and OSX. .. image:: http://i.imgur.com/Ek13lqM.png @@ -22,7 +22,6 @@ RTV is built in **python** using the **curses** library. * `Configuration`_ * `FAQ`_ * `Changelog`_ -* `Contributors`_ * `License`_ ============ @@ -33,98 +32,34 @@ Install using pip .. code-block:: bash - $ sudo pip install rtv + $ pip install rtv -Or clone the repository +or clone the repository .. code-block:: bash $ git clone https://github.com/michael-lazar/rtv.git $ cd rtv - $ sudo python3 setup.py install + $ python3 setup.py install -The installation will place a script in the system path +and run it .. code-block:: bash $ rtv - $ rtv --help -See the `FAQ`_ to troubleshoot common installation problems +See the `FAQ`_ for troubleshooting ===== Usage ===== -RTV supports browsing both subreddits and submission comments. - -Navigating is simple and intuitive. Move the cursor using either the arrow keys or *Vim* style movement. -Move **up** and **down** to scroll through the page. -Move **right** to view the selected submission, and **left** to exit the submission. +Press **up** and **down** to scroll through submissions. +Press **right** to view the selected submission and **left** to return. +Press **?** to open the help screen. --------------- -Basic Commands --------------- - -:``j``/``k`` or ``▲``/``▼``: Move the cursor up/down -:``m``/``n`` or ``PgUp``/``PgDn``: Jump to the previous/next page -:``1-5``: Toggle post order (*hot*, *top*, *rising*, *new*, *controversial*) -:``r`` or ``F5``: Refresh page content -:``u``: Log in or switch accounts -:``?``: Show the help screen -:``q``/``Q``: Quit/Force quit - ----------------------- -Authenticated Commands ----------------------- - -Some actions require that you be logged in to your reddit account. -You can log in by pressing ``u`` while inside of the program. -Once you are logged in your username will appear in the top-right corner of the screen. - -:``a``/``z``: Upvote/downvote -:``c``: Compose a new post or comment -:``e``: Edit an existing post or comment -:``d``: Delete an existing post or comment -:``i``: Display new messages prompt -:``s``: View a list of subscribed subreddits - --------------- -Subreddit Mode --------------- - -In subreddit mode you can browse through the top submissions on either the front page or a specific subreddit. - -:``l`` or ``►``: Enter the selected submission -:``o`` or ``ENTER``: Open the submission link with your web browser -:``/``: Open a prompt to switch subreddits -:``f``: Open a prompt to search the current subreddit - -The ``/`` prompt accepts subreddits in the following formats - -* ``/r/python`` -* ``/r/python/new`` -* ``/r/python+linux`` supports multireddits -* ``/r/front`` will redirect to the front page -* ``/r/me`` will display your submissions - ---------------- -Submission Mode ---------------- - -In submission mode you can view the self text for a submission and browse comments. - -:``h`` or ``◄``: Return to the subreddit -:``o`` or ``ENTER``: Open the comment permalink with your web browser -:``SPACE``: Fold the selected comment, or load additional comments - - -======= -Key Map -======= - -.. image:: http://i.imgur.com/xDUQ03C.png +See `CONTROLS.rst `_ for the complete list of commands. ============= Configuration @@ -134,41 +69,38 @@ Configuration Editor ------ -RTV allows users to compose comments and replies using their preferred text editor (**vi**, **nano**, **gedit**, etc). -You can specify which text editor you would like to use by setting the ``$RTV_EDITOR`` environment variable. +You can compose posts and reply to comments using your preferred text editor. +Specify the editor by setting ``$RTV_EDITOR`` in your environment. .. code-block:: bash $ export RTV_EDITOR=gedit -If no editor is specified, RTV will fallback to the system's default ``$EDITOR``, and finally to ``nano``. +If not specified, the default system ``$EDITOR`` (or *nano*) will be used. ----------- Web Browser ----------- -RTV has the capability to open links inside of your web browser. -By default RTV will use the system's browser. -On most systems this corresponds to a graphical browser such as Firefox or Chrome. -If you prefer to stay in the terminal, use ``$BROWSER`` to specify a console-based web browser. +You can open submission links using your web browser. +On most systems the default web browser will open in a new window. +If you would prefer the complete terminal experience, set ``$BROWSER`` to a console-based web browser. `w3m `_, `lynx `_, and `elinks `_ are all good choices. -.. code-block:: bash - - $ export BROWSER=w3m - -------------- Authentication -------------- -RTV uses OAuth to facilitate logging into your reddit user account [#]_. The login process follows these steps: +RTV allows you to login to your reddit account in order to do things like vote and leave comments. +The login process uses OAuth [#]_ and follows these steps: +1. Initiate a login by pressing the ``u`` key. +2. Open a new webpage where reddit will ask you to authorize the application. +3. Click accept. -1. You initiate a login by pressing the ``u`` key. -2. You're redirected to a webbrowser where reddit will ask you to login and authorize RTV. -3. RTV uses the generated token to login on your behalf. -4. The token is stored on your computer at ``{HOME}/.config/rtv/refresh-token`` for future sessions. You can disable this behavior by setting ``persistent=False`` in your RTV config. +RTV will retrieve your new auth token and store it locally in ``{HOME}/.config/rtv/refresh-token``. +You can disable storing the token by setting ``persistent=False`` in the config. -Note that RTV no longer allows you to input your username/password directly. This method of cookie based authentication has been deprecated by reddit and will not be supported in future releases [#]_. +Note that RTV no longer allows you to input your username/password directly. This method of cookie based authentication has been deprecated by reddit [#]_. .. [#] ``_ .. [#] ``_ @@ -177,14 +109,14 @@ Note that RTV no longer allows you to input your username/password directly. Thi Config File ----------- -RTV stores configuration settings in ``{HOME}/.config/rtv/rtv.cfg``. -You can auto-generate the config file by running +Configuration settings are stored in ``{HOME}/.config/rtv/rtv.cfg``. +Auto-generate the config file by running .. code-block:: bash $ rtv --copy-config -See the `default config `_ to view descriptions for each setting. +See the `default config `_ for a list of settings. === FAQ @@ -218,19 +150,12 @@ How do I run the repository code directly? ========= Changelog ========= -Please see `CHANGELOG.rst `_. - - -============ -Contributors -============ -Please see `CONTRIBUTORS.rst `_. - +Please see the `change log `_. ======= License ======= -Please see `LICENSE `_. +This project is distributed under the `MIT `_ license. .. |python| image:: https://img.shields.io/badge/python-2.7%2C%203.5-blue.svg diff --git a/rtv/config.py b/rtv/config.py index 53be7de..7519653 100644 --- a/rtv/config.py +++ b/rtv/config.py @@ -27,7 +27,7 @@ def build_parser(): parser = argparse.ArgumentParser( prog='rtv', description=docs.SUMMARY, - epilog=docs.CONTROLS+docs.HELP, + epilog=docs.CONTROLS, formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument( '-V', '--version', action='version', version='rtv '+__version__) diff --git a/rtv/docs.py b/rtv/docs.py index eb7503f..af5bdfa 100644 --- a/rtv/docs.py +++ b/rtv/docs.py @@ -12,13 +12,8 @@ terminal window. """ CONTROLS = """ -Controls --------- -RTV currently supports browsing both subreddits and individual submissions. -In each mode the controls are slightly different. In subreddit mode you can -browse through the top submissions on either the front page or a specific -subreddit. In submission mode you can view the self text for a submission and -browse comments. +Move the cursor using either the arrow keys or *Vim* style movement. Open the +help screen by pressing the `?` key. """ HELP = """