i hate myself so much why do i waste time writing something nobody will read and programming something for nothing
sophuwu sophie@skisiel.com
Sun, 08 Sep 2024 14:07:21 +0200
2 files changed,
40 insertions(+),
29 deletions(-)
M
README.md
→
README.md
@@ -1,7 +1,9 @@
# Go Man Page Web Server + This Go application serves man pages over HTTP. It allows users to view, search, and browse man pages directly from a web browser. The server dynamically integrates the hostname into the pages and provides static file support (CSS and favicon). ## Table of Contents + - [Features](#features) - [Dependencies](#dependencies) - [Compiling The Binary](#compiling-the-binary)@@ -10,6 +12,7 @@ - [Accessing the Web Interface](#accessing-the-web-interface)
- [Notes and Warnings](#notes-and-warnings) ## Features + - Convert any man page into HTML, formatted for easy reading. With a dark theme. - Search functionality to find specific man pages. Wildcards and regex are supported. - Hyperlinked pages for easy navigation for any valid reference in the document, and the ability to open the page in a new tab.@@ -19,12 +22,16 @@ - Able to correctly interpret and display incorrectly formatted man pages, to a degree.
- Auto updates man pages when new packages are installed or removed using standard installation methods. ## Dependencies + `mandoc` is required for parsing. Ubuntu/Debian/apt installation: + ```sh sudo apt-get install mandoc -y ``` + `go v1.21.5` or greater is required to build the source code. Official installation instructions at [go.dev](https://go.dev/doc/install).\ Quick and lazy script to install go 1.23.1 (Tested on Ubuntu 07-SEP-2024): + ```sh [ -d /usr/local/go ] && sudo rm -rf '/usr/local/go' ; # delete incompatible versions which wget || sudo apt-get install wget -y && wget https://go.dev/dl/go1.23.1.linux-amd64.tar.gz ; # downlaod compatible version@@ -47,12 +54,14 @@ sudo install ./build/manhttpd /usr/local/bin/manhttpd
``` ## Using As Systemd Service: + The provided service file should work on most systems, but you may need to edit it to fit your needs.\ It will open a http server on port 8082 available through all network interfaces.\ You should change the `ListenAddr` variable to `127.0.0.1` and use a secure reverse proxy if you are on a public network.\ TLS and authentication are not implemented in this server. ### Variables in the service file: + Environment Variables:\ `HOSTNAME`: Used for http proxying.\ `ListenPort`: If unset, the server will default to 8082.\@@ -60,6 +69,7 @@ `ListenAddr`: This should be changed if you are on a public network.\
`MANDOCPATH`: Path to the mandoc executable. If unset, the server will attempt to find it in the PATH. ### System Variables: + `User`: Reccomended to use your login user so the service can access your ~/.local man pages. But not required.\ `ExecStart`: The path to the manhttpd binary. If you installed it to /usr/local/bin, you can leave it as is.\ `WorkingDirectory`: This should be /tmp since the server doesn't need to write to disk.\@@ -68,56 +78,57 @@ ```sh
# to edit paths, users, and environment variables if needed nano manhttpd.service -# install the service file to systemd +# install the service file to systemd and load it sudo install manhttpd.service /etc/systemd/system/manhttpd.service -# reload the systemd daemon to load the new service sudo systemctl daemon-reload -# to start the service and check its status +# start the service and check its status sudo systemctl start manhttpd.service sudo systemctl status manhttpd.service -# if you would like the service to run when the system boots +# to keep the service running after a reboot sudo systemctl enable manhttpd.service -# to stop the service and disable it from starting automatically +# to stop the service and disable it from restarting sudo systemctl stop manhttpd.service sudo systemctl disable manhttpd.service -# if you would like to change the variables in the service file -sudo systemctl stop manhttpd.service +# to edit the server configuration after installation sudo systemctl edit manhttpd.service sudo systemctl daemon-reload -sudo systemctl start manhttpd.service - ``` - +sudo systemctl reload-or-restart manhttpd.service +sudo systemctl status manhttpd.service +``` ## Accessing the Web Interface + Open your web browser and navigate to `http://localhost:8082` if you are running the server locally or the remote server's IP address or hostname.\ To search with regex, you can use the search bar at the top of the page with `-r` at the beginning of the search term.\ To look into a specific section, you can add `-sN` to the search term where N is the section number.\ If no section is specified, the server will display with the same priority as the defualt `man` command.\ Glob patterns are also supported in the search bar if regex not enabled.\ -Example search terms: -- `ls*`: List all pages that begin with `ls`. -- `-r ^ls`: Same as above but with regex. -- `ls` or `ls -s1` or `ls.1`: Open the page for the `ls` user command. -- `-r ^ls -s1`: List all pages that begin with `ls` in section 1 (user/bin commands). -- `*config* -s8`: List all pages that contain `config` within the name and are in section 8 (sudo/sbin commands). -- `vsftpd.5`: Open the manual page for vsftpd confuguration file if vsftpd is installed. -- `vsftpd.8`: Open the manual page for vsftpd executable if vsftpd is installed. +## Example Usage: + +- `ls*`: List all pages that begin with `ls`, including `ls`, `lsblk`, `lsmod`, etc. +- `-r ^ls`: Same as above but with regex. Usually more useful for with multiple queries and logical operators. Like finding any C++ reference to `std::string` and `std::vector`. +- `ls` or `ls -s1` or `ls.1`: Open the page for the `ls` user command. This is orignal man behavior. +- `-r ^ls -s1`: List all pages that begin with `ls` in section 1 (user/bin commands). Useful for finding commands that list any information without requiring sudo. +- `*config* -s8`: List pages for sudo commands containing keyword `config`. this can will show you commands that edit critical system files. +- `vsftpd.5`: Open the manual page for vsftpd confuguration file if vsftpd is installed. This will show you how to configure the ftp server. +- `vsftpd.8`: Open the manual page for vsftpd executable if vsftpd is installed. This will show how to call the ftp server from the command line. ## Notes and Warnings -- packages installed with apt or dpkg will automatically be available -- manual pages may be unavailable if the package is not installed or the manuals are not included by the package -- all manual pages that are correctly installed and comply with the manpath will be searchable and viewable -- manuals that do not comply with the manpath will not be available for viewing may show up in search results -The application serves the following embedded static files: -- `index.html`: The main HTML template, which includes placeholders for the server's hostname. -- `dark_theme.css`: The CSS stylesheet used to style the web interface. No light theme is provided. -- `favicon.ico`: A favicon served with the site. -I do not recommend changing anything in index.html. CSS classes are hardcoded into the man pages and will not render if changed.\ -However, changing the css rules in your browser's developer tools to see how it affects the page is a good way to test changes.\ -You can then rebuild the binary with the changes you like to make the changes permanent. +- Regex syntax may vary when running on systems with differing core c/c++ libraries. +- Manual pages may be unavailable if the package is not installed or the manuals are not included by the package. +- All manual pages that are correctly installed and comply with the manpath will be searchable and viewable. +- Manuals that do not comply with the manpath will not be available for viewing may show up in search results. +- If you would like to change the css styling, you should avoid changing the names, ids, or classes of the elements as they are dynamically generated. Instead, you can add properties to the existing classes or ids, or change the values of the properties. +- the static web files are embedded into the server binary so changes to css properties will require you to recompile the binary. + +## Help and Support + +I don't know how this git pull thing works. I will try if I see any issues. I've never collaborated on code before. If you have any suggestions, or questions about anything I've written, I would be happy to hear your thoughts.\ +contant info: (skisiel.com)[https://skisiel.com]\ +```