type: guide
The World Wide Web has a ton of content. Much/most of it will not be converted to this new system. Eventually there will be a time when there needs to be some interoperability between SuperTXT, commands, and the simple browser.
Starting with links, web links are URL/URI, while SuperTXT are just commands. What does a mapping between the two look like? It turns out that there's a fairly straight forward way to convert web links to SuperTXT.
URL: http://somesite.com/foo/bar/baz?a=b&cd= Command: somesite.com --a=b --c=d foo/bar/baz
The protocol portion, mostly "http" or "https", can be discarded since it's a low-level detail. Instead, there is a site-specific command (somesite.com) installed on the local system that takes care of the internal network communication with the site. It could be using http(s) underneath, but that's an internal contract between the tool and the site. The URL's path is encoded as a single path argument to the command. The query parameters become options where the option is the key and the option's value is the value of the query parameter.
Ideally, the site-specific command can output SuperTXT, and support the command reflection to inform the browser of the expected file extension of the content produced on STDOUT. But, this is not the only option for a site-specific tool. Another option for this tool is that outputs some plain text, or other type of content that can be understood by the browser or command-line. Perhaps the tool has its own graphical user interface for a rich site experience.
Using commands instead of URL's has some other nice features too. Check out this example of how spaces are handled in both cases. The command is arguably much easier to read than the URL.
URL: http://somesite.com/foo%20bar/Document%201%20Appendix?q=a+b+c+d+e+f+g Command: somesite.com "-q=a b c d e f g" "foo bar/Document 1 Appendix"
If the site-specific command is not present, then there are some possible fallbacks. One is to run the "open" command with the full URL so that a web browser can show the link, subject to whether the open command is trusted by the browser/shell, of course.
An SSH server could host its content as a website in parallel to help facilitate linking to it from the web. Incoming HTTP requests can be served by local files using the path.
http://somesite.com/directory/file.s.txt => directory/file.s.txt
Since the files are simple text, the response header can specify the "Content-Type" as "text/plain." An intelligent server implementation can automatically convert a SuperTXT document into HTML upon request if the extension of the resource is ".html". It's possible that in a future state web browsers will support a "text/super+plain" content type with enhanced display and native link traversal features.
http://somesite.com/directory/file.html # Server makes the SuperTXT into HTML before serving it to the web browser
An intelligent SSH server can do the same sort of content negotiation. For example, if a command requests a ".pdf", but there's a SuperTXT file with the same base name, then the server could auto-generate the PDF from the source document.
HTTP has a number of features, such as response headers, that can exist in SuperTXT in a different form. The headers that exist in HTTP are generally hidden from view of the user. This is not ideal according to our principles. Headers in SuperTXT are most closely mapped to points that appear either underneath the top-level heading of the document, or if there is no top-level heading then at the very top of the document. Points are visible to the user so that they can see them.
Request headers are generally mapped to command-line concepts, such as arguments, options, flags, and file extensions. Each command is free to interpret these in a command-specific way. For example, a specific file extension for a file requested from the command line determines the type of content displayed to the user. This is a form of content negotiation.
Every HTTP response includes a status, such as 200, which means "OK". There are a variety of other status codes with specific meanings. SuperTXT inherits the idea of exit codes from the command-line where an exit code of 0 means successand any other value represents some manner of failure, usually with details of the error on STDERR for the user to read. Other sorts of standardized status codes, such as redirect don't exist in this environment, but a command is free to provide its own instructions, such as recommending a new location for the document.
In this guide we have looked at how to support different kinds of interoperability with The World Wide Web. URL's encountered by a browser, or SuperTXT document, can be easily mapped into a site-specific command where the interactions with the website is abstracted, but then it can be made compatible with browser or command-line shell. In the worst case, the site-specific command can be a thin wrapper around open, which can open a real web browser to display the link. Links to SuperTXT documents made by websites can also be made into URL's with a web server that serves up the documents as either plain text, or automatically generated HTML appearance. HTTP, which is the transfer protocol for websites has features such as request/response headers, and status codes, which map to SuperTXT points, arguments, options, and command-line exit codes.
HAVE SOME FEEDBACK ON THIS DOCUMENT?
You can provide a conventional comment on this document.
ssh nobody@supertxt.net ccmnt specs/web-interop.s.txt <<EOF suggestion: Here's my actionable suggestion. EOF