From 1c0295e32e26872ddfc6ab526c9e46f3c800efa5 Mon Sep 17 00:00:00 2001 From: sloumdrone Date: Tue, 15 Oct 2019 20:07:54 -0700 Subject: [PATCH 1/4] Updates readme to better fit the 2.0.0 build methodology --- README.md | 56 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 9bf3b31..d9859ad 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # Bombadillo -Bombadillo is a modern [Gopher](https://en.wikipedia.org/wiki/Gopher_(protocol)) client for the terminal, and functions as a pager/terminal UI. Bombadillo features vim-like keybindings, configurable settings, and a robust command selection. Bombadillo is under active development. +Bombadillo is a non-web client for the terminal, and functions as a pager/terminal UI. Bombadillo features vim-like keybindings, configurable settings, and a robust command selection. Currently, Bombadillo supports the following protocols: +- gopher +- gemini +- finger +- local (a user's filesystem) +- telnet (by opening links in a subprocess w/ a telnet application) +- http/https links can be opened in a user's default web browser as an opt-in behavior ## Getting Started @@ -9,29 +15,49 @@ These instructions will get a copy of the project up and running on your local m ### Prerequisites -If building from source, you will need to have [Go](https://golang.org/) version >= 1.11. Bombadillo uses the module system, so if using 1.11 you will need to have that feature enabled. If using a version > 1.11, you already have modules enabled. +If building from source, you will need to have [Go](https://golang.org/) version >= 1.12. -Bombadillo does not use any outside dependencies beyond the Go standard library. +### Building, Installing, Uninstalling -### Installing +Bombadillo installation uses `make`. It is possible to just use the go compiler directly (`go install`) if you do not wish to have a man page installed and do not want a program to manage uninstalling and cleaning up. -Assuming you have `go` installed, run the following: +By default Bombadillo will try to install to `$GOBIN`. If it is not set it will try `$GOPATH/bin` (if `$GOPATH` is set), otherwise `~/go/bin`. + +#### Basic Installation + +Once you have `go` installed you can build a few different ways. Most users will want the following: ``` git clone https://tildegit.org/sloum/bombadillo.git cd bombadillo -go install +make install ``` -Once you have done that you should, assuming `go install` is set up to install to a place on your path, you should be able to run the following from anywhere on your system to use Bombadillo: +Once that is done you should be able to run `bombadillo` (assuming that one of the default install locations exists and is on your path) or view the manual with `man bombadillo`. + +#### Custom Installation + +There are a number of default configuration options in the file `defaults.go`. These can all be set prior to building in order to have these defaults apply to all users of Bombadillo on a given system. That said, the basic configuration already present should be suitable for most users (and all settings but one can be changed from within a Bombadillo session). + +The installation location can be overridden at compile time, which can be very useful for administrators wanting to set up Bombadillo on a multi-user machine. If you wanted to install to, for example, `/usr/local/bin` you would do the following: ``` -bombadillo +git clone https://tildegit.org/sloum/bombadillo.git +cd bombadillo +make install BUILD_PATH=/usr/local/bin +``` + +#### Uninstall + +If you used the makefile to install Bombadillo then uninstalling is very simple. From the Bombadillo source folder run: + +``` +make uninstall ``` #### Troubleshooting -If you run `bombadillo` and get `bombadillo: command not found`, try running `go build` from within the cloned repo. Then try: `./bombadillo`. If that works it means that Go does not install to your path. `go build` added an executable file to the repo directory. Move that file to somewhere on your path. I suggest `/usr/local/bin` on most systems, but that may be a matter of personal preference. +If you run `bombadillo` and get `bombadillo: command not found`, try running `make build` from within the cloned repo. Then try: `./bombadillo`. If that works it means that Go does not install to your path, or the custom path you selected is not on your path. Try the custom install from above to a location you know to be on your path. ### Downloading @@ -39,21 +65,17 @@ If you would prefer to download a binary for your system, rather than build from ### Documentation -Bombadillo has documentation available in four places currently. The first is the [Bombadillo homepage](https://rawtext.club/~sloum/bombadillo.html#docs), which has lots of information about the program, links to places around Gopher, and documentation of the commands and configuration options. +Bombadillo's primary documentation can be found in the man entry that installs with Bombadillo. To access it run `man bombadillo` after first installing Bombadillo. If for some reason that does not work, the document can be accessed directly from the source folder with `man ./bombadillo.1`. -Secondly, and possibly more importantly, documentation is available via Gopher from within Bombadillo. When a user launches Bombadillo for the first time, their `homeurl` is set to the help file. As such they will have access to all of the key bindings, commands, and configuration from the first run. A user can also type `:?` or `:help` at any time to return to the documentation. Remember that Bombadillo uses vim-like key bindings, so scroll with `j` and `k` to view the docs file. - -Thirdly, this repo contains a file `bombadillo-info`. This is a duplicate of the help file that is hosted over gopher mentioned above. Per user request it has been added to the repo so that pull requests can be created with updates to the documentation. - -Lastly, but perhaps most importantly, a manpage is now included in the repo as `bombadillo.1`. Current efforts are underway to automate the install of both bombadillo and this manpgage. +In addition to the man page, users can get information on Bombadillo on the web @ [http://bombadillo.colorfield.space](http://bombadillo.colorfield.space). Running the command `help` inside Bombadillo will navigate a user to the gopher server hosted at [bombadillo.colorfield.space](gopher://bombadillo.colorfield.space), specifically the user guide. ## Contributing -Bombadillo development is largely handled by Sloum, with help from jboverf, asdf, and some community input. If you would like to get involved, please reach out or submit an issue. At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. If you have forked and would like to make a pull request, please make the pull request into `develop` where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. +Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and some community input. If you would like to get involved, please reach out or submit an issue. At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. If you have forked and would like to make a pull request, please make the pull request into `develop` where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. While input is always welcome, not all requests will be granted. That said, we do our best to make Bombadillo a useful piece of software for its users and in general want to help you out. ## License -This project is licensed under the GNU GPL version 3- see the [LICENSE](LICENSE) file for details. +This project is licensed under the GNU GPL version 3. See the [LICENSE](LICENSE) file for details. ## Releases From f4e5209f24b8f20a6338591d5b506ba909c624e5 Mon Sep 17 00:00:00 2001 From: Brian Evans Date: Mon, 28 Oct 2019 11:48:16 -0700 Subject: [PATCH 2/4] Updates readme to be more current with the develop branch --- README.md | 62 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index d9859ad..bea3519 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,95 @@ # Bombadillo -Bombadillo is a non-web client for the terminal, and functions as a pager/terminal UI. Bombadillo features vim-like keybindings, configurable settings, and a robust command selection. Currently, Bombadillo supports the following protocols: -- gopher -- gemini -- finger -- local (a user's filesystem) -- telnet (by opening links in a subprocess w/ a telnet application) -- http/https links can be opened in a user's default web browser as an opt-in behavior +Bombadillo is a non-web client for the terminal, and functions as a pager/terminal UI. Bombadillo features vim-like keybindings, configurable settings, and a robust command selection. Currently, Bombadillo supports the following protocols as first class citizens: +* gopher +* gemini +* finger +* local (a user's filesystem) + +Support for the following protocols is also available via integration with 3rd party applications: +* telnet + * By opening links in a subprocess w/ a telnet application +* http/https + * Web support is opt-in (turned off by default) + * Links can be opened in a user's default web browser when in a graphical environment + * Web pages can be rendered directly in Bombadillo if [Lynx](https://lynx.invisible-island.net/) is installed on the system to handle the document parsing. ## Getting Started -These instructions will get a copy of the project up and running on your local machine. +These instructions will get a copy of the project up and running on your local machine. The following only applies if you are building from source (rather than using a precompiled binary). ### Prerequisites -If building from source, you will need to have [Go](https://golang.org/) version >= 1.12. +You will need to have [Go](https://golang.org/) version >= 1.11. ### Building, Installing, Uninstalling -Bombadillo installation uses `make`. It is possible to just use the go compiler directly (`go install`) if you do not wish to have a man page installed and do not want a program to manage uninstalling and cleaning up. +Bombadillo installation uses `make`. It is also possible to just use the go compiler directly (`go install`), but this is not the recommended approach. -By default Bombadillo will try to install to `$GOBIN`. If it is not set it will try `$GOPATH/bin` (if `$GOPATH` is set), otherwise `~/go/bin`. +By default running `make` from the source code directory will build Bombadillo in the local directory. This is fine for testing or trying things out. But for usage systemwide and easy access to documentation, you will likely want to install. #### Basic Installation -Once you have `go` installed you can build a few different ways. Most users will want the following: +Most users will want to isntall via the following: ``` git clone https://tildegit.org/sloum/bombadillo.git cd bombadillo -make install +sudo make install ``` +Note: the usage of sudo here will be system dependent. Most systems will require it for installation to `/usr/local/bin`. -Once that is done you should be able to run `bombadillo` (assuming that one of the default install locations exists and is on your path) or view the manual with `man bombadillo`. +You can then run `bombadillo` or familiarize yourself with the application by running `man bombadillo`. #### Custom Installation There are a number of default configuration options in the file `defaults.go`. These can all be set prior to building in order to have these defaults apply to all users of Bombadillo on a given system. That said, the basic configuration already present should be suitable for most users (and all settings but one can be changed from within a Bombadillo session). -The installation location can be overridden at compile time, which can be very useful for administrators wanting to set up Bombadillo on a multi-user machine. If you wanted to install to, for example, `/usr/local/bin` you would do the following: +The installation location can be overridden at compile time, which can be very useful for administrators wanting to set up Bombadillo on a multi-user machine. ``` git clone https://tildegit.org/sloum/bombadillo.git cd bombadillo -make install BUILD_PATH=/usr/local/bin +sudo make DESTDIR=/some/directory install ``` +There are two things to know about when using the above format: +1. The above would install Bombadillo to `/some/directory/usr/local/bin`, _not_ to `/some/directory`. So you will want to make sure your `$PATH` is set accordingly. +2. Using the above will install the man page to `/some/directory/usr/local/share/man`, rather than its usual location. You will want to update your `manpath` accordingly. + #### Uninstall If you used the makefile to install Bombadillo then uninstalling is very simple. From the Bombadillo source folder run: ``` -make uninstall +sudo make uninstall ``` +If you used a custom `DESTDIR` value during install, you will need to supply it when uninstalling: +``` +sudo make DESTDIR=/some/directory uninstall +``` + +Uninstall will clean up any build files, remove the installed binary, and remove the manpage from the system. If will _not_ remove any directories created as a part of the installation, nor will it remove any Bombadillo user configuration files. + #### Troubleshooting -If you run `bombadillo` and get `bombadillo: command not found`, try running `make build` from within the cloned repo. Then try: `./bombadillo`. If that works it means that Go does not install to your path, or the custom path you selected is not on your path. Try the custom install from above to a location you know to be on your path. +If you run `bombadillo` and get `bombadillo: command not found`, try running `make build` from within the cloned repo. Then try: `./bombadillo`. If that works it means that the application is getting built correctly and the issue is likely in your path settings. Any errors during `make install` should be pretty visible, as you will be able to see what command it failed on. ### Downloading -If you would prefer to download a binary for your system, rather than build from source, please visit the [Bombadillo downloads](https://rawtext.club/~sloum/bombadillo.html#downloads) page. Don't see your OS/architecture? Bombadillo can be built for use with any POSIX compliant system that is supported as a target for the Go compiler (Linux, BSD, OS X, Plan 9). No testing has been done for Windows. The program will build, but will likely not work properly outside of the Linux subsystem. If you are a Windows user and would like to do some testing or get involved in development please reach out or open an issue. +If you would prefer to download a binary for your system, rather than build from source, please visit the [Bombadillo releases](http://bombadillo.colorfield.space/releases) page. Don't see your OS/architecture? Bombadillo can be built for use with any system that is supported as a target for the Go compiler (Linux, BSD, OS X, Plan 9). There is no explicit support for, or testing done for, Windows or Plan 9. The program should build on those systems, but you may encounter unexpected behaviors or incompatibilities. ### Documentation Bombadillo's primary documentation can be found in the man entry that installs with Bombadillo. To access it run `man bombadillo` after first installing Bombadillo. If for some reason that does not work, the document can be accessed directly from the source folder with `man ./bombadillo.1`. -In addition to the man page, users can get information on Bombadillo on the web @ [http://bombadillo.colorfield.space](http://bombadillo.colorfield.space). Running the command `help` inside Bombadillo will navigate a user to the gopher server hosted at [bombadillo.colorfield.space](gopher://bombadillo.colorfield.space), specifically the user guide. +In addition to the man page, users can get information on Bombadillo on the web @ [http://bombadillo.colorfield.space](http://bombadillo.colorfield.space). Running the command `help` inside Bombadillo will navigate a user to the gopher server hosted at [bombadillo.colorfield.space](gopher://bombadillo.colorfield.space); specifically the user guide. ## Contributing -Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and some community input. If you would like to get involved, please reach out or submit an issue. At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. If you have forked and would like to make a pull request, please make the pull request into `develop` where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. While input is always welcome, not all requests will be granted. That said, we do our best to make Bombadillo a useful piece of software for its users and in general want to help you out. +Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and some community input. If you would like to get involved, please reach out or submit an [issue](https://tildegit.org/sloum/bombadillo/issues). At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. If you have forked and would like to make a pull request, please make the pull request into `develop` where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. While input is always welcome, not all requests will be granted. That said, we do our best to make Bombadillo a useful piece of software for its users and in general want to help you out. ## License @@ -79,5 +97,5 @@ This project is licensed under the GNU GPL version 3. See the [LICENSE](LICENSE) ## Releases -Starting with v2.0.0 releases into `master` will be version-tagged. Work done toward the next release will be created on work branches named for what they are doing and then merged into `develop` to be combined with other ongoing efforts before a release is merged into `master`. At present there is no specific release schedule. It will depend on the urgency of the work that makes its way into develop and will but up to the project maintainers' judgement when to release from `develop`. +Starting with v2.0.0 releases into `master` will be version-tagged. Work done toward the next release will be created on work branches named for what they are doing and then merged into `develop` to be combined with other ongoing efforts before a release is merged into `master`. At present there is no specific release schedule. It will depend on the urgency of the work that makes its way into develop and will be up to the project maintainers' judgement when to release from `develop`. From ab6037d39d6f163b28cf024a5aa927cc0f4dccc5 Mon Sep 17 00:00:00 2001 From: asdf Date: Tue, 29 Oct 2019 21:19:14 +1100 Subject: [PATCH 3/4] Initial review --- README.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bea3519..2c0ca0e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ # Bombadillo -Bombadillo is a non-web client for the terminal, and functions as a pager/terminal UI. Bombadillo features vim-like keybindings, configurable settings, and a robust command selection. Currently, Bombadillo supports the following protocols as first class citizens: +Bombadillo is a non-web client for the terminal, and functions as a pager/terminal UI. + +Bombadillo features vim-like keybindings, configurable settings, and a robust command selection. Currently, Bombadillo supports the following protocols as first class citizens: * gopher * gemini * finger -* local (a user's filesystem) +* local (a user's file system) Support for the following protocols is also available via integration with 3rd party applications: * telnet - * By opening links in a subprocess w/ a telnet application + * Links are opened in a telnet application run as a subprocess * http/https * Web support is opt-in (turned off by default) * Links can be opened in a user's default web browser when in a graphical environment @@ -25,22 +27,29 @@ You will need to have [Go](https://golang.org/) version >= 1.11. ### Building, Installing, Uninstalling -Bombadillo installation uses `make`. It is also possible to just use the go compiler directly (`go install`), but this is not the recommended approach. +Bombadillo installation uses `make`. It is also possible to use Go to build and install (i.e `go build`, `go install`), but this is not the recommended approach. -By default running `make` from the source code directory will build Bombadillo in the local directory. This is fine for testing or trying things out. But for usage systemwide and easy access to documentation, you will likely want to install. +Running `make` from the source code directory will build Bombadillo in the local directory. This is fine for testing or trying things out. For usage system-wide, and easy access to documentation, follow the installation instructions below. #### Basic Installation -Most users will want to isntall via the following: +Most users will want to install using the following commands: ``` git clone https://tildegit.org/sloum/bombadillo.git cd bombadillo sudo make install ``` -Note: the usage of sudo here will be system dependent. Most systems will require it for installation to `/usr/local/bin`. +*Note: the usage of `sudo` here will be system dependent. Most systems will require it for installation to `/usr/local/bin`.* -You can then run `bombadillo` or familiarize yourself with the application by running `man bombadillo`. +You can then start Bombadillo by running the command: +``` +bombadillo +``` +To familiarize yourself with the application, documentation is available by running the command: +``` +man bombadillo +``` #### Custom Installation @@ -71,11 +80,11 @@ If you used a custom `DESTDIR` value during install, you will need to supply it sudo make DESTDIR=/some/directory uninstall ``` -Uninstall will clean up any build files, remove the installed binary, and remove the manpage from the system. If will _not_ remove any directories created as a part of the installation, nor will it remove any Bombadillo user configuration files. +Uninstall will clean up any build files, remove the installed binary, and remove the man page from the system. If will _not_ remove any directories created as a part of the installation, nor will it remove any Bombadillo user configuration files. #### Troubleshooting -If you run `bombadillo` and get `bombadillo: command not found`, try running `make build` from within the cloned repo. Then try: `./bombadillo`. If that works it means that the application is getting built correctly and the issue is likely in your path settings. Any errors during `make install` should be pretty visible, as you will be able to see what command it failed on. +If you run `bombadillo` and get `bombadillo: command not found`, try running `make` from within the cloned repo. Then try: `./bombadillo`. If that works it means that the application is getting built correctly and the issue is likely in your path settings. Any errors during `make install` should be pretty visible, as you will be able to see what command it failed on. ### Downloading @@ -89,7 +98,11 @@ In addition to the man page, users can get information on Bombadillo on the web ## Contributing -Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and some community input. If you would like to get involved, please reach out or submit an [issue](https://tildegit.org/sloum/bombadillo/issues). At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. If you have forked and would like to make a pull request, please make the pull request into `develop` where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. While input is always welcome, not all requests will be granted. That said, we do our best to make Bombadillo a useful piece of software for its users and in general want to help you out. +Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and some community input. If you would like to get involved, please reach out or submit an issue. + +At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. + +If you have forked and would like to make a pull request, please make the pull request into develop where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. While input is always welcome, not all requests will be granted. That said, we do our best to make Bombadillo a useful piece of software for its users and in general want to help you out. ## License @@ -97,5 +110,5 @@ This project is licensed under the GNU GPL version 3. See the [LICENSE](LICENSE) ## Releases -Starting with v2.0.0 releases into `master` will be version-tagged. Work done toward the next release will be created on work branches named for what they are doing and then merged into `develop` to be combined with other ongoing efforts before a release is merged into `master`. At present there is no specific release schedule. It will depend on the urgency of the work that makes its way into develop and will be up to the project maintainers' judgement when to release from `develop`. +Starting with version 2.0.0 releases into `master` will be version-tagged. Work done toward the next release will be created on work branches named for what they are doing and then merged into `develop` to be combined with other ongoing efforts before a release is merged into `master`. At present there is no specific release schedule. It will depend on the urgency of the work that makes its way into develop and will be up to the project maintainers' judgement when to release from `develop`. From a9654a6804be3754d94ba7e8ba46001488546620 Mon Sep 17 00:00:00 2001 From: asdf Date: Fri, 1 Nov 2019 13:32:59 +1100 Subject: [PATCH 4/4] Expanded the contributing section --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2c0ca0e..a342cb7 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Uninstall will clean up any build files, remove the installed binary, and remove #### Troubleshooting -If you run `bombadillo` and get `bombadillo: command not found`, try running `make` from within the cloned repo. Then try: `./bombadillo`. If that works it means that the application is getting built correctly and the issue is likely in your path settings. Any errors during `make install` should be pretty visible, as you will be able to see what command it failed on. +If you run `bombadillo` and get `bombadillo: command not found`, try running `make` from within the cloned repo. Then try: `./bombadillo`. If that works it means that the application is getting built correctly and the issue is likely in your path settings. Any errors during `make install` should be visible, and you will be able to see what command it failed on. ### Downloading @@ -98,11 +98,19 @@ In addition to the man page, users can get information on Bombadillo on the web ## Contributing -Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and some community input. If you would like to get involved, please reach out or submit an issue. +Bombadillo development is largely handled by Sloum, with help from asdf, jboverf, and community input. -At present the developers use the tildegit issues system to discuss new features, track bugs, and communicate with users about hopes and/or issues for/with the software. +There are many ways to contribute to Bombadillo, including a fair few that don't require knowledge of programming: -If you have forked and would like to make a pull request, please make the pull request into develop where it will be reviewed by one of the maintainers. That said, a heads up or comment/issue somewhere is advised. While input is always welcome, not all requests will be granted. That said, we do our best to make Bombadillo a useful piece of software for its users and in general want to help you out. +- Try out the client and let us know if you have a suggestion for improvement, or if you find a bug. +- Read the documentation and let us know if something isn't well explained, or needs correction. +- Maybe you have a cool logo or some art that you think would look nice. + +If you have something in mind, please reach out or [open an issue](https://tildegit.org/sloum/bombadillo/issues). + +We aim for simplicity and quality, and do our best to make Bombadillo useful to its users. Any proposals for change are reviewed by the maintainers with this in mind, and not every request will be accepted. Furthermore, this software is developed in our spare time for the good of all, and help is provided as best efforts. In general, we want to help! + +The maintainers use the [tildegit](https://tildegit.org) issues system to discuss new features, track bugs, and communicate with users regarding issues and suggestions. Pull requests should typically have an associated issue, and should target the `develop` branch. ## License @@ -111,4 +119,3 @@ This project is licensed under the GNU GPL version 3. See the [LICENSE](LICENSE) ## Releases Starting with version 2.0.0 releases into `master` will be version-tagged. Work done toward the next release will be created on work branches named for what they are doing and then merged into `develop` to be combined with other ongoing efforts before a release is merged into `master`. At present there is no specific release schedule. It will depend on the urgency of the work that makes its way into develop and will be up to the project maintainers' judgement when to release from `develop`. -