go_clientinfo/server/tpl/usage.html.tpl

{{- /*gotype: r00t2.io/clientinfo/server.Page*/ -}}
{{- define "usage" }}
{{- $page := . -}}
{{- $linkico := "🔗" }}
{{- template "meta.top" $page }}
				<div class="jumbotron">
					<h1>Usage</h1>
				</div>
				<h2 id="usage_params">Parameters<a href="#usage_params">{{ $linkico }}</a></h2>
				<p>
					You can control how the <a href="/">main page</a> displays/renders.
					By default, it will try to "guess" what you want; e.g. if you access it in Chrome, it will return HTML but if you fetch via Curl, you'll get raw JSON
					(or your specified data format; see below). If the classification of client can't be determined and an <code>Accept</code> wasn't specified,
					a fallback to text-mode (by default <code>application/json</code>) will be returned.
					<br/>

					You can force a specific raw output by specifying the <a href="https://www.iana.org/assignments/media-types/media-types.xhtml">MIME type</a> via
					<a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1">the <code>Accept</code> header (RFC 9110 &sect; 12.5.1)</a>, which may be one of:
					<ul>
						<li><code>application/json</code> for <a href="https://www.rfc-editor.org/rfc/rfc8259.html">JSON</a></li>
						<li><code>application/xml</code> for <a href="https://www.rfc-editor.org/rfc/rfc7303.html">XML</a></li>
						<li><code>application/yaml</code> for <a href="https://www.rfc-editor.org/rfc/rfc9512.html">YAML</a></li>
						<li><code>text/html</code> for <a href="https://www.rfc-editor.org/rfc/rfc2854.html">HTML</a></li>
					</ul>
					For example: <code>Accept: application/json</code> will return JSON.
					<br/>

					If unspecified and it is a text-mode client (e.g. Curl), the default is <code>application/json</code>.
					<code>text/html</code> may be used to force an HTML response from a text-only client,
					just as one of the <code>application/*</code> MIME types above may be used to force that "raw" text MIME type for a "graphical" browser client.
					The specification as defined by <a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1">RFC 9110 &sect; 12.5.1</a> is completely
					valid to pass and will be parsed without error (provided the header value is RFC-compliant and IANA-compliant),
					though note that <code>application/xml</code> and <code>text/html</code>'s <code>charset</code> parameter will be entirely ignored;
					the returned XML/HTML is <b>always</b> Unicode (with UTF-8 encoding).
					<br/>

					If no selectable MIME type is provided but an <code>Accept</code> was given, an error will be returned; specifically, a
					<a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.7"><code>406</code> status code (RFC 9110 &sect; 15.5.7)</a>.
					In this case, supported MIME types will be returned in the response's <code>Accept</code> header.
					<br/>

					Note that <a href="https://lynx.invisible-island.net/">Lynx</a> and <a href="http://elinks.or.cz/">Elinks</a> are considered "graphical"
					browsers by this program as they are HTML-centric.
				</p>
				<p id="usage_params_mod">
					The following parameters control/modify behavior.<a href="#usage_params_mod">{{ $linkico }}</a>
					<ul>
						<li>
							<b>mime:</b> Specify an explicit MIME type via URL instead of the <code>Accept</code> header as specified above.
							<ul>
								<li>This should only be used by clients in which it is impossible or particularly cumbersome to modify/specify headers.
									<code>Accept</code> is more performant.</li>
								<li>Only the first supported instance of this parameter will be used.</li>
								<li>Any of the defined MIME types above may be specified (e.g. <code>?mime=application/json</code>).</li>
								<li>If both this URL query parameter and the <code>Accept</code> header is specified, the URL query takes preference.</li>
							</ul>
						</li>
						<li>
							<b>include:</b> Include a <code>&lt;code&gt;</code> (or <code>&lt;pre&gt;</code>, depending on if indentation is needed/requested) block in the HTML for the specified MIME type as well.</li>
							<ul>
								<li>Only the first supported instance of this parameter will be used.</li>
								<li>
									The value <b>must</b> conform to the same rules/specifications as the <code>mime</code> parameter/<code>Accept</code> header.
									<ul>
										<li><code>include</code> may <b>not</b> be <code>text/html</code>; it will be ignored if this is set. Just learn to <code>ctrl+u</code>.</li>
									</ul>
								</li>
								<li>Only used if the evaluated return is HTML, ignored otherwise.</li>
								<li>Indentation can be specified via the <b>indent</b> parameter below (since indentation is otherwise meaningless to HTML returns).</li>
							</ul>
						</li>
						<li>
							<b>indent:</b> Enable/specify indentation for JSON and XML output; ignored for others.
							<ul>
								<li>The default is to not indent. (Commonly referred to as "condensed" or "compressed" JSON/XML.)</li>
								<li>Only the first specified instance of this parameter will be used.</li>
								<li>If specified with a string value, use that string as each indent.
									<ul>
										<li>Be mindful of URL query parameter encoding,
											per <a href="https://www.rfc-editor.org/rfc/rfc3986.html#section-3.4">RFC 3986 &sect; 3.4</a>
											and <a href="https://www.rfc-editor.org/rfc/rfc8820.html#section-2.4">RFC 8820 &sect; 2.4</a></li>
										<li>For quick reference and as an example, to indent with a <a href="https://asciiref.dev/#c9">tab</a>
											(<code>\t</code>, <code>0x09</code>) for each level, use <code>?indent=%09</code></li>
									</ul>
								</li>
								<li>If indentation is specified without any value (<code>?indent</code>), the default is two
									<a href="https://asciiref.dev/#c32">spaces</a> (<code>0x20</code>); this would be represented
									as <code>?indent=%20%20</code></li>
								<li><code>?indent=</code> (no value specified) is equal to <code>?indent</code>.</li>
							</ul>
						</li>
					</ul>
				</p>
{{- template "meta.bottom" $page }}
{{- end }}