README-tools.md (11172B)
1 # Bopher Tools: a set of simple Bash scripts to not just browse Gopher but also create content for it 2 3 Bopher Tools is a small collection of simple shell scripts that: 4 5 - are written in pure Bash with no external dependencies (unless explicitly stated otherwise); 6 - are totally independent from each other (but can be combined in the true spirit of Unix philosophy); 7 - only accept input from stdin and only output their results into stdout; 8 - aim to ease your life when it comes to creating and publishing your own content in Gopherspace. 9 10 It is recommended to distribute these scripts along with the main Bopher-NG client, although everyone is free to redistribute them in any other form. Just like the main Bopher-NG script, all these tools are released into public domain. Their documentation is added to this page in the chronological order they were created. 11 12 Without further ado, let's begin! 13 14 ## `gopherinfo.sh` 15 16 This tool converts every line of the standard input into a valid CRLF-terminated Gophermap line of the `i` type that obeys RFC1436. It accepts three **optional** parameters: the number of leading spaces (0 by default), the number of trailing spaces (0 by default) and the placeholder (';' by default) to put into the selector and host fields unused in the `i` type (and the port field is always set to 0). It also pads every input line with the amount of spaces required to make the line length the same as the longest one in the input. All this is done to make your output Gophermap look nice when viewed in plaintext as well. 17 18 Note that the tool **does not** output the trailing dot to end the Gophermap, because its output can be used as a part of another Gophermap. To end the map manually according to the RFC1436, just invoke `printf '.\r\n'` afterwards redirecting to the same output. 19 20 Example of using `gopherinfo.sh` in combination with FIGlet, using 4 leading spaces, 0 trailing spaces and `|` as the placeholder (CR and Tab characters in the output are not shown): 21 ``` 22 $ figlet 'Bash it' | bash gopherinfo.sh 4 0 '|' 23 i ____ _ _ _ | | 0 24 i | __ ) __ _ ___| |__ (_) |_ | | 0 25 i | _ \ / _` / __| '_ \ | | __| | | 0 26 i | |_) | (_| \__ \ | | | | | |_ | | 0 27 i |____/ \__,_|___/_| |_| |_|\__| | | 0 28 i | | 0 29 ``` 30 31 A non-trivial task would be using this output in some Web-based services like Happy Net Box. You have to paste it in a format that the browser's text input element wouldn't mess with. To do this, you need the following steps: 32 33 1. Pipe the `gopherinfo.sh` output into the autoquoter like this: `| ( read -rsd '' x; printf '%q\n' "$x" )` 34 2. Copy everything except the first dollar sign of the output to your clipboard. 35 3. In your Web browser, open a developer console (F12), type `console.log()` and put the cursor between the brackets. 36 4. Paste your escaped string and hit Enter. If everything went correctly, the output should not be mangled. 37 5. Copy your `console.log` output again (make sure to fully copy the last line too!) and paste it in your Web service's posting textarea. 38 39 This hack also appies to any Gophermaps and not just the fragments generated with this tool. 40 41 Or, if you happen to have a working clipboard, you can just pipe the tools' output to `| xsel -bi` (on Linux) or `| pbcopy` (on Mac) and try pasting it directly. In all probability, it might work, but no one can guarantee. 42 43 ## `phlow.sh` 44 45 This tool processes every line of text from the standard input to fit exactly the given amount of characters, optionally adding some leading and/or trailing whitespaces **after** the reflow is done. It also replaces all LF line endings with CRLF in the output to achieve maximum compatibility with legacy clients. 46 47 As `phlow.sh` does not know anything about hyphenation rules and doesn't do any heuristics, it just breaks at whatever whitespace is the closest to the page's right edge. 48 49 Example - fitting the previous paragraph into 30-character width and prepending every line with 5 spaces (CR characters in the output are not shown): 50 ``` 51 $ echo 'This tool processes every line of text from the standard input to fit exactly the given amount of characters, optionally adding some leading and/or trailing whitespaces **after** the reflow is done. It also replaces all LF line endings with CRLF in the output to achieve maximum compatibility with legacy clients.' | bash phlow.sh 30 5 52 This tool processes every 53 line of text from the 54 standard input to fit 55 exactly the given amount of 56 characters, optionally 57 adding some leading and/or 58 trailing whitespaces 59 **after** the reflow is 60 done. It also replaces all 61 LF line endings with CRLF in 62 the output to achieve 63 maximum compatibility with 64 legacy clients. 65 ``` 66 67 ## `gmi2map.sh` 68 69 This tool converts Gemtext documents into browsable Gophermaps. It basically combines the functionality of both previous tools and adds link processing and triple-backtick removal (because in Gopherspace, all text is supposed to be preformatted) on top of them. Unlike `gopherinfo.sh` though, it doesn't care about the maximum length of the source (if you need to, the reflow logic is there), but it **is** expecting the entire document from the standard input, and as such, **does** add the trailing dot at the end of the generated Gophermap. That's why, for the beginners, this sole script might actually be everything you need to get you started with Gopher publishing. 70 71 Note that by default, reflow logic in `gmi2map.sh` is optional and you have to specify the page width yourself if you need it. Actually, full usage syntax looks like this: 72 ``` 73 cat [file] | gmi2map.sh [page_width] [leading_spaces] [trailing_spaces] [placeholder_char] 74 ``` 75 76 I.e. it looks like the `phlow.sh` and `gopherinfo.sh` options combined, but the spaces part only applies to the reflow, which is also off by default. Also, it doesn't align the whitespaces after the infolines unless there is non-zero amount of trailing spaces. 77 78 Example - imagine we have this rudimentary Gemtext document in the `example.gmi` file: 79 ``` 80 I write short Gemtext here. 81 82 I write a bit longer Gemtext here to showcase reflow capabilities of Bopher Tools' gmi2map.sh script, because it really is cool. 83 84 => gopher://happynetbox.com:79/1luxferre Anyway, why not publish it on Gopher? 85 => https://chronovir.us Or read my blog on Web... 86 87 See ya! 88 ``` 89 90 When running `cat example.gmi | bash gmi2map.sh 67 0 1`, this file translates to the following Gophermap: 91 92 ``` 93 $ cat example.gmi | bash gmi2map.sh 67 94 iI write short Gemtext here. ; ; 0 95 i ; ; 0 96 iI write a bit longer Gemtext here to showcase reflow capabilities ; ; 0 97 iof Bopher Tools' gmi2map.sh script, because it really is cool. ; ; 0 98 i ; ; 0 99 1Anyway, why not publish it on Gopher? luxferre happynetbox.com 79 100 hOr read my blog on Web... URL:https://chronovir.us ; 0 101 i ; ; 0 102 iSee ya! ; ; 0 103 . 104 ``` 105 106 Note that this tool hasn't been tested for all possible edge cases yet, so I recommend to always verify the generated maps yourself. But it definitely makes their creation a lot easier than doing it by hand. 107 108 ## `gmi2txt.sh` 109 110 This tool converts Gemtexts into CRLF-terminated and preformatted plaintext files ready to be served on Gopher. It has the same parameters as `gmi2map.sh` sans the placeholder character. Link lines are converted to the `[description]: [url]` format and, unlike `gmi2map.sh`, also are subject to reflows like everything else. 111 112 Example - imagine we have this rudimentary Gemtext document in the `example.gmi` file: 113 ``` 114 I write short Gemtext here. 115 116 I write a bit longer Gemtext here to showcase reflow capabilities of Bopher Tools' gmi2txt.sh script, because it really is cool. 117 118 => gopher://happynetbox.com:79/1luxferre Visit my Gopher homepage 119 => https://chronovir.us Or read my blog on Web 120 121 See ya! 122 ``` 123 124 When running `cat example.gmi | bash gmi2txt.sh 67 5`, this file translates to the following plaintext: 125 ``` 126 I write short Gemtext here. 127 128 I write a bit longer Gemtext here to showcase reflow capabilities 129 of Bopher Tools' gmi2txt.sh script, because it really is cool. 130 131 Visit my Gopher homepage: gopher://happynetbox.com:79/1luxferre 132 Or read my blog on Web: https://chronovir.us 133 134 See ya! 135 ``` 136 137 ## `list2map.sh` 138 139 This tool, which probably is the smallest but the most sophisticated one in the entire collection, accepts the list of files and directories (possibly generated with `find` command) and generates, line by line, a portion of Gophermap based on their type (for this, it requires the external `file` command dependency), root directory name and hostname/port number optionally passed to the script on invocation. The tool automatically applies the following rules: 140 141 - only the basename part of the file/directory is used as the entry name/description; 142 - if the file is a directory (MIME type `inode/directory`), the generated selector will actually refer to the `index.map` file in that directory and the entry type will be 1; 143 - files (or directories) named `index.map` are not themselves included in the output; 144 - if the file's MIME type starts with `text`, the entry type will be set to 0, otherwise it will be set to 9. 145 146 Note that the tool itself doesn't do any filtering on input names or how they are presented. All filtering, if necessary, should be done on the `find` invocation step. 147 148 Example - build a Gophermap fragment from this repo's starting directory, excluding all dotfiles, using `.` as root and assuming we'll serve this map from `example.com:777`: 149 ``` 150 $ find . ! -path '.' ! -path '*/.*' | bash tools/list2map.sh . example.com 777 151 0COPYING /COPYING example.com 777 152 1tools /tools/index.map example.com 777 153 0gopherinfo.sh /tools/gopherinfo.sh example.com 777 154 0phlow.sh /tools/phlow.sh example.com 777 155 0gmi2map.sh /tools/gmi2map.sh example.com 777 156 0gmi2txt.sh /tools/gmi2txt.sh example.com 777 157 0README-tools.md /tools/README-tools.md example.com 777 158 0list2map.sh /tools/list2map.sh example.com 777 159 0bopher-ng.sh /bopher-ng.sh example.com 777 160 0README.md /README.md example.com 777 161 ```