README (17267B)

 tao_shells
 ----------
 Text user interface(TUI) for everyday computer/device tasks.
 
 
 Usage
 -----
 
     $ tao_bluetooth_connect # Connect to bt device
     $ tao_copy.sh $1        # Yank $1
     $ tao_copy.sh -         # Yank stdin
     $ tao_notes.sh          # Notes
     $ tao_pactl_setsink.sh  # Set audio output device
     $ tao_url.sh            # Open url
     $ tao_url.sh -q         # Internet query
     $ tao_url.sh -y         # Download and play youtube video
     $ tao_youtube_query.sh  # Youtube videos from listed channels
 
 
 Base Requirements
 ------------
 - your-favorite-terminal-emulator
 - your-favorite-text-editor
 - dmenu (or bemenu/rofi)
 - wget
 
 
 Youtube Requirements
 --------------------
 - yt-dlp
 - mediaplayer
 
 
 Turn Key Out of the Box Requirements / Default Opener Options
 ---------------------------------------------------------------
 - st
 - dmenu
 - wget
 - mpv
 - yt-dlp
 - Gui browsers (qutebrowser, firefox, surf)
 - Tui browsers (w3m, links)
 - nsxiv (images)
 - zathura (pdfs)
 
 
 Description
 -----------
 Shell scripts minimizing machine time, maximizing tao time.
 
 This is for the CLI and TUI folks in the crowd. If you are already a
 unix-based/linux user and live in the GUI, I encourage you to explore
 the command line and become familiar with the terminal environment. To
 get started, using a terminal text editor (e.g. vim) is a great way to
 get your hands dirty. You'll be searching for files cli style and
 editing them all in the terminal. Maybe start a journal this way.
 
 The tao_url.sh is a core utility that has undergone maybe 6 rewrites. I
 learn something new and then all of a sudden, everything needs to be
 rewritten. And I do enjoy the process. It is a hobby of mine. And I feel
 these scripts are in a good enough place to be shared. So here we are.
 Welcome the tao shells.
 
 The purpose of these programs, particularly tao_url, is to minimize
 distraction in our lives. The internet is a massive distraction
 downpour. The tao_url.sh is not an umbrella, it removes you from the
 storm and keeps you above it, as much as it can. The idea is to pull
 things out of the storm, into your the light of your home, for
 intentional purposes. tao_url.sh is there to help users take control and
 hone their relationship with the internet. So how does it work. The
 primary interface is suckless.org's wonderful dmenu. If you are an X11
 user, please install dmenu ( See dmenu below ). If you are running a
 Wayland environment, you'll want to install bemenu. Rofi will also work.
 But one of the three are required to use the tao shells. How each tao
 shell program works is outlined below.
 
 
 Install
 -------
 Clone the git repo.
 
     $ git clone git://watertao.xyz/programs/tao_shells.git
 
 cd into tao_shells directory.
 
     $ cd tao_shells
 
 cp the files into your user's local bin. Assuming ~/.local/bin it your
 user executable directory, following should do it:
 
     $ a=~/.local/bin/; for i in *.sh; do cp $i $a$i; chmod a+x $a$i; done
 
 Check that ~/.local/bin is in your PATH env. If you already are setup
 with a user local executable path, just be sure to install the shells
 respectively.
 
 Also, see TERMINAL in the Environment Variables section below.
 
 Based on the requirements that suit your need, install any programs
 and/or configure the tao_opener.conf file accordingly. See
 tao_opener.conf section below.
 
 
 ### Rofi
 If using rofi, you'll need to set some flags for rofi to work well.
 After your initial run of tao_url.sh which will have created the tao
 config directory, the following command should do the trick:
 
 Likely most window tiling manager environments:
 
     printf "%s\n" "-dmenu" > ~/.config/tao/tao_dmenu.conf
 
 Deeply GUI environments (ie Ubuntu Gnome):
 
     printf "%s\n" "-dmenu -normal-window" > ~/.config/tao/tao_dmenu.conf
 
 
 Environment Variables
 ---------------------
 A word regarding env vars first. Although not required, you may set the
 following to the programs you run on your local system:
 
 - TERMINAL
 - DMENU
 - EDITOR
 
 For the unlettered, please refer to your shell's man page for further
 reading on environment variables.
 
 If unset, tao shells will try to discover each for the following programs:
 
 - TERMINAL=st,urxvt,xterm
 - DMENU=dmenu,rofi,bemenu
 
 The tao shells do no work whatsoever in the search for an EDITOR. This
 invaluable antique is entirely on you and absolutely a necessity.
 
 
 tao_url.sh
 ----------
 There is a lot going on here with such a simple utility, so get a cup
 coffee or tea or water, get your cozy's on, and let's get into it.
 
 First, the flow of what happens when this program runs.
 
 
 ### Url mode:
 
 01
 
 You are prompted to enter a url. The dmenu list will be populated with
 history and bookmarks below the prompt. As you type, the fuzzy find
 reduces the list accordingly. You can quickly find history urls and
 bookmarks this way, or simply enter a fresh url to do something with.
 And because dmenu is amazing, it's fast.
 
 02
 
 After url selection, you are prompted with a list of programs.  How will
 you be opening or using this url? Web browsers of course are a natural
 method. Defaults are qutebrowser, firefox, w3m, and links (See Text
 Browsers below on why w3m and links are important). You can also
 bookmark or yank(copy) the url from this menu. More on those tasks
 below. If the url is an image file, you can run by default nsxiv to view
 it. If an a/v url, mpv is there as an option. With images and video
 urls, by selecting their respective openers, you'll be asked first if
 you'd like to download the file first. In most case, unless it's a/v,
 downloading first is and excellent idea. More on that later.
 
 03
 
 If you're opening the url with a browser, you'll be off and running. If
 downloading first, you'll see a terminal open running wget to download
 the file, then once completed, the respective opener will launch and
 you'll be greeted with the content requested.
 
 
 ### Query mode:
 You are afforded the same steps as above, with a few important
 differences.
 
 01
 
 You are prompted initally for query/search terms instead of a url
 address. The history of your searches will be at your disposal as you
 type.
 
 02
 
 Once your query is ready, you can select any browser to open it, and the
 default duckduckgo will provide the results. If it is a youtube video,
 you can ytdlp/mpv option is there to download first, then mpv play the
 video locally.
 
 
 ### Youtube:
 See Youtube Videos below.
 
 
 ### Local mode:
 I'd avoid using this for now. It's well overdue for some tuning. I
 never use it anymore, I don't recommend it, and as such may be
 removed entirely in the unforseeable future.
 
 
 So why is this important. Why inject all these questions and steps into
 simply opening a url. Please see Ethos below.
 
 
 dmenu
 -----
 I will be writing more about dmenu in the future, quite likely when I've
 uploaded my dmenu configurations to the git server here, maybe never,
 who knows. For now my recommendation is to first download it from your
 distro's repo and explore it's usage a bit. Once your hooked, you'll
 want to customize the aesthetic, in which case I recommend cloning the
 git repo from suckless.org along with relevant patches, get all that
 building without error, sort out your config.def.h, and you'll be a
 happier dmenu user on the other side.
 
 
 Text Browsers
 -------------
 I will save the ethos of text browsers for the Ethos section below.
 Briefly, text browsing is a valuable and important step in taking
 control of your relationship with the internet. Text browsing is exactly
 as it sounds. A web page is requested from its server, and the content
 is returned to your client, as usual. The only difference is your client
 runs in a terminal window, and that's a big difference. Javascript is
 supported in some text browsers, but style sheets and images are all
 stripped. Image placeholders are often used for awareness of the
 material and in the case you wish to view it, options are available for
 media consumption.
 
 In using a text browser, you laser focus your usage of content retrieved
 from the internet. More on that in Ethos below. The learning curve and
 comfort acclimation are very real here. Out of the gates, parsing lines
 of text visually is an entirely different and an uncomfortable
 experience. It was worth the struggle for me. It may be for you too. It
 may not. Whatever it is. It's ok.
 
 
 Youtube Videos
 --------------
 For the ethos portion of this discussion, see Ethos. This section
 focuses on the usage of youtube content using tao_url.sh and
 tao_youtube_query.sh.
 
 
 ### Download and view:
 Running 'tao_url.sh -r', type or paste the youtube video link, hit
 Enter, then you are prompted as usual with a list of opener options.
 Select 'yt/mpv' to download first, then play locally using mpv.
 
     tao_url.sh -r; [enter link]; yt/mpv;
 
 
 ### Streaming video:
 Same process as 'Download and view' above, except instead of 'yt/mpv',
 simply open with 'mpv' instead. You'll be prompted to 'Download first?',
 whereupon you'll answer no, and mpv will begin streaming the video.
 
     tao_url.sh -r; [enter link]; mpv; n;
 
 
 ### Search:
 tao_url.sh -q as usual for internet searching, including youtube.  After
 entering/selecting keywords to search, in the opener prompt, select 'yt
 search'. You are then presented with a list of youtube videos. Once a
 video is selected, you'll be prompted with opener options, 'yt/mpv' to
 download then view, or 'mpv' for streaming.
 
     tao_url.sh -q; [enter search words]; yt search;
 
 
 ### Channel videos:
 Same process as above for download/view/streaming, except for the url,
 you enter a youtube channel's url, then select either of the two 'yt
 channel...' options. The first limits the video list to 50 for speed of
 service purposes. The other gets fetches everything, takes a little
 longer, but worth it if you're digging into history.
 
     tao_url.sh -r; [enter yt channel address]; yt channel; [select video]; ...
 
 
 ### Fetching latest videos from a list of channels:
 With a populated tao_channel_fetch_latest.sites config file, running
 tao_youtube_query.sh fetches a list of latest videos from every listed
 channel, sorts in date order, and offers this list for your perusal and
 selection, dmenu style. As many videos as you like can be launched using
 yt/mpv opener option, as each video will download in its own terminal
 window and play automatically once respective download completes. A nice
 way to catch up very quickly with channels of interest.
 
     tao_youtube_query.sh;
 
 
 ### Recommended keybinds for your window manager:
     tao_url.sh -r
     tao_url.sh -q
     tao_youtube_query.sh
 
 
 Files
 -----
 ```
 ~/.local/share/tao/
     url/
         bookmark
         history
         query
 
 ~/.config/tao/
     tao_channel_fetch_latest.sites
     tao_dmenu.conf
     tao_openers.conf
     tao_url.conf
 
 tao_url.conf optional variables:
     TAO_QUERY_ENG
     TAO_EXEC_IN_TERM
     TAO_DL_THEN_OPEN
 ```
 
 
 tao_url.conf
 ------------
 ### TAO_QUERY_ENG
 Set the query url for search engine in tao_url.conf. Default:
 
     TAO_QUERY_ENG="https://ddg.gg?q="
 
 
 tao_opener.conf
 ---------------
 Upon initial use of tao_url.sh, ~/.config/tao/tao_opener.conf is auto
 generated if not already exists. It contains a default opener/program
 list, the tao_url.sh task menu for urls. See Turn-key Out of the Box
 Requirements for the default list. The format for program entries is as
 follows:
 
 menu name (optional) %% program :: tags (optional)
 
 Examples:
 
     w3m :: TERM
     firefox
     mpv %% mpv --msg-level=ffmpeg/video=error :: DL_OPT MEDIA_PLAYER TERM
     nsxiv :: DL
 
 
 ### yt/* and ytdlp/mpv
 
 Embedded tao_url.sh Commands:
     ytdlp/mpv
     yt/channel[/[0-9]+]
     yt/query[/[0-9]+]
 
 Although a ytdlp/mpv and yt/* names can be customized for the menu, the
 command names cannot be changed. And tags do not apply and if added, will
 break the command.
 
 All yt/* commands can take a results limit, which takes the format of a
 number tacked onto the end of the command. Without an assigned limit,
 all is fetched. See "Acceptable" examples below.
 
 Acceptable:
 
     ytdlp/mpv
     ytdlp custom menu name %% ytdlp/mpv
     yt channel limit 10 custom name %% yt/channel/10
     yt/channel
     yt search %% yt/query
     yt search limit 80 results %% yt/query/80
 
 Unacceptable:
 
     ytdlp/mpv :: tags that should not be here
     yt custom menu name %% yt-wrong-name-for-ytdlp/mpv-command
     yt custom menu name %% ytdlp/mpv :: tags that should not be here
 
 
 ### Opener Tags
 
 DL
 
 wget downloads url first, then program selected opens it.
 
 DL_OPT
 
 Same as DL, but offered as an interactive option. This is useful with
 mpv for example, where you can opt to not download and just run the url
 with mpv, whereupon the video is streamed. Or you can choose to download
 first then play locally. Each has their advantages.
 
 MEDIA_PLAYER
 
 Sets the program as the yt/mpv media player where the entire program
 call including options and flags is used to run the downloaded youtube
 video. Only one program is used with this tag, if multiple programs are
 tagged with this, the first in the list is used. If the tag isn't used,
 the default player is mpv.
 
 TERM
 
 Launch the program in a terminal. Text browsers such as w3m are fine
 candidates of this tag. If you wish to monitor the stdout/err msgs from
 any program, this tag is useful.
 
 
 Ethos: Computers and our Relationship with the Internet
 -------------------------------------------------------
 What's the point of all of this? I happen to be a shell scripting
 hobbyist. So crafting these ui scripts is actually enjoyable.  That's
 really important. I live by few rules. One of them is to die smiling, at
 any point. Life takes its turns and it's not always easy to say that. I
 know I need to make moves if it is untrue. And so my engagement shifts.
 This is the wildness of wind in a creature that normally strongly
 associates with the stillness of trees.
 
 Crafting a user interface layer between me and the system, including the
 internet not only keeps me above the mess but allows me to use a system
 in an aesthetic that very much resonates, as so much of one's self
 reflects in the end product. That's an element, and also important.
 
 So there's the personal gain for me. But what about beyond that? Is
 there any gain for you or I to actually use these things?
 
 The full story of what's happening in our devices every time we use
 them, actually even while they sit idly in our pockets, is a story
 extraordinarily outside the scope of this writing. So we will focus for
 a moment only on the internet. Spoiler and tldr;, the internet sucks.
 
 Something I appreciate deeply about suckless.org is their name. The
 acknowledgement is inherent. Software sucks. All of it. They attempt to
 provide software that merely sucks less. This is especially true
 regarding the internet. Web browsers are terrible. All of them. The best
 can be found in text browsers. I love every one of them, even with all
 their sucktitude. So lets speak softly for a moment on the merits and
 ethos of using text browsers instead of gui.
 
 The internet lure is strong. It doesn't take much to keep a user simply
 connected to and aimlessly using the internet. A web page with nicely
 aligned and admirably spaced, sized and fonted text, featuring a simple
 yet pleasant color palette is all it takes. We are attracted to design.
 Design is art and art is emotional. I'm not talking about crying over
 page layout, I speaking to that thing that happens in us when something
 feels good.  Even subtly so.  When information becomes entertaining, we
 are roughly one click away from falling deeper into the digital world of
 our devices. Pure distraction awaits. The astronomical level of life
 distraction is merely one problem among many. The social, physical,
 religious and political...  in a word, mass cultural effect of the
 internet alone is something else entirely. I say all of this not to
 completely overshadow any benefit that may be gleaned from this monster.
 Communication is critical to understanding the world of humanity at the
 very least. So to harness the communicative power of interconnected
 devices simultaneously mitigating the damage is something I attribute
 likely too much thought too entirely. But here we are. I'm going to cut
 off all these half thoughts to end what is really only a README file for
 some shell scripts.
 
 The bottom line is to maximize our time alive, with life itself. Our
 actual, analog, very real bodies, minds, souls and hearts. Our own, and
 the others in our company. The internet is intended to be a trustless
 system, and we ought to use it as such, and use it far far less. Less
 endless scrolling, "screen time" of digital consumption. Less
 surveillance of our lives by strangers we do not know and ought not
 trust. The internet has it's uses, and the tao shells exist to leverage
 the positives and diminish the spell. These tools and so many others
 alike in the wild are here to help humanity return to humanity.
 
 
 Notes
 -----
 Every idea introduced in this file can be grossly expanded upon, and
 most certainly has been done so by many others. These are mere notes to
 a handful of utilities for the unix/linux user. There exist other tao
 shells for a myriad of other tasks, and when the time comes that they
 find comfort within themselves, they will walk out the front door as
 these shells have done and join the world of open source.