diff --git a/man7/uri.7 b/man7/uri.7 index 4770c172e..4cd881187 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -81,7 +81,8 @@ the resource ceases to exist or becomes unavailable. .PP URIs are the standard way to name hypertext link destinations for tools such as web browsers. -The string "http://www.kernelnotes.org" is a URL (and thus it's a URI). +The string "http://www.kernelnotes.org" is a URL (and thus it +is also a URI). Many people use the term URL loosely as a synonym for URI (though technically URLs are a subset of URIs). .PP @@ -164,7 +165,8 @@ are embedded in SGML/XML documents (including HTML), the ampersand (&) has to be rewritten as &. Note that not all queries use this format; larger forms may be too long to store as a URI, so they use a different -interaction mechanism (called POST) which does not include the data in the URI. +interaction mechanism (called POST) which does +not include the data in the URI. See the Common Gateway Interface specification at for more information. .SS "ftp \- File Transfer Protocol (FTP)" @@ -282,8 +284,8 @@ An example of this scheme is . .RI man: command-name ( section ) .PP This refers to local online manual (man) reference pages. -The command name can optionally be followed by a parenthesis and section number; -see +The command name can optionally be followed by a +parenthesis and section number; see .BR man (7) for more information on the meaning of the section numbers. This URI scheme is unique to Unix-like systems (such as Linux) @@ -299,7 +301,8 @@ An example is . .RI info:( virtual-filename ) nodename .PP This scheme refers to online info reference pages (generated from -texinfo files), a documentation format used by programs such as the GNU tools. +texinfo files), +a documentation format used by programs such as the GNU tools. This URI scheme is unique to Unix-like systems (such as Linux) and is not currently registered by the IETF. As of this writing, GNOME and KDE differ in their URI syntax @@ -318,8 +321,8 @@ Examples of the KDE format are and . .SS "whatis \- Documentation search" .RI whatis: string .PP -This scheme searches the database of short (one-line) descriptions of commands -and returns a list of descriptions containing that string. +This scheme searches the database of short (one-line) descriptions of +commands and returns a list of descriptions containing that string. Only complete word matches are returned. See .BR whatis (1). @@ -389,7 +392,7 @@ a comma-separated list of type=value pairs, where the =value portion may be omitted for options not requiring it. An extension prefixed with a '!' is critical -(must be supported to be valid), otherwise it's non-critical (optional). +(must be supported to be valid), otherwise it is non-critical (optional). .PP LDAP queries are easiest to explain by example. Here's a query that asks ldap.itd.umich.edu for information about @@ -553,9 +556,10 @@ use the standard format as described here. .UE .SH NOTES Any tool accepting URIs (e.g., a web browser) on a Linux system should -be able to handle (directly or indirectly) all of the schemes described here, -including the man: and info: schemes. -Handling them by invoking some other program is fine and in fact encouraged. +be able to handle (directly or indirectly) all of the +schemes described here, including the man: and info: schemes. +Handling them by invoking some other program is +fine and in fact encouraged. .PP Technically the fragment isn't part of the URI. .PP @@ -568,8 +572,8 @@ Texinfo files use the format @uref{\fIuri\fP}. Man and mdoc have the recently-added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI). .PP -The GNOME and KDE desktop environments currently vary in the URIs they accept, -in particular in their respective help browsers. +The GNOME and KDE desktop environments currently vary in the URIs +they accept, in particular in their respective help browsers. To list man pages, GNOME uses while KDE uses , and to list info pages, GNOME uses while KDE uses (the author of this man page prefers the KDE approach here, though a more @@ -582,8 +586,8 @@ GNOME prefers the ghelp scheme to store and find documentation. Neither browser handles file: references to directories at the time of this writing, making it difficult to refer to an entire directory with a browsable URI. -As noted above, these environments differ in how they handle the info: scheme, -probably the most important variation. +As noted above, these environments differ in how they handle the +info: scheme, probably the most important variation. It is expected that GNOME and KDE will converge to common URI formats, and a future version of this man page will describe the converged result. @@ -640,15 +644,16 @@ References of the form don't work because different distributions and local installation requirements may place the files in different directories -(it may be in /usr/doc, or /usr/local/doc, or /usr/share, or somewhere else). +(it may be in /usr/doc, or /usr/local/doc, or /usr/share, +or somewhere else). Also, the directory ZZZ usually changes when a version changes (though filename globbing could partially overcome this). -Finally, using the file: scheme doesn't easily support people who dynamically -load documentation from the Internet (instead of loading the files -onto a local filesystem). +Finally, using the file: scheme doesn't easily support people +who dynamically load documentation from the Internet (instead of +loading the files onto a local filesystem). A future URI scheme may be added (e.g., "userdoc:") to permit -programs to include cross-references to more detailed documentation without -having to know the exact location of that documentation. +programs to include cross-references to more detailed documentation +without having to know the exact location of that documentation. Alternatively, a future version of the filesystem specification may specify file locations sufficiently so that the file: scheme will be able to locate documentation. @@ -658,9 +663,9 @@ or implement links using URIs. .PP Many programs can't handle all of these different URI formats; there should be a standard mechanism to load an arbitrary URI that automatically -detects the users' environment (e.g., text or graphics, desktop environment, -local user preferences, and currently-executing tools) and invokes the -right tool for any URI. +detects the users' environment (e.g., text or graphics, +desktop environment, local user preferences, and currently-executing +tools) and invokes the right tool for any URI. .\" .SH AUTHOR .\" David A. Wheeler (dwheeler@dwheeler.com) wrote this man page. .SH "SEE ALSO"