Editing 1692: Man Page

{{comic
| number    = 1692
| date      = June 10, 2016
| title     = Man Page
| image     = man_page.png
| titletext = For even more info, see blarbl(2)(3) and birb(3ahhaha I'm kidding, just Google it like a normal person.
}}

==Explanation==
This comic shows a {{w|Unix}} manual page, i.e. a ''{{w|man page}}'' (hence the title), for a fictional program called "[http://www.urbandictionary.com/define.php?term=blerp blerp]". Unix man pages are meant to provide a brief reference on the usage of a command, not extended explanations with tutorials as may be found in many hardcopy product manuals. Unfortunately, some Unix commands tend to be very bloated and include lots of optional behavior that is often irrelevant to the original intent of the command and can be done much more easily using shell features like piping and redirection, and thus the manpage grows to explain all of the features. This example exaggerates the obscurity and terseness found in many man pages, making fun of the typical style of the genre.

It follows the prescribed format for a man page, with the following sections:
*Command Name: self-explanatory
*Synopsis: a synopsis of the valid command line formats
*Description: a summary of the purpose and operation of the command
*Options: detailed description of all the available command line arguments
*See Also: references to other man pages with relevance
*Bug Reports: contact details for the support group (if any)
*Copyright: details of the ownership and rights status of the man page (not the program)

For comic effect, most of this particular man page is not meaningful, and sometimes doesn't obey the expected syntax.

The Synopsis section is supposed to be in a {{w|Regular Expression|regex}}-like language called {{w|Wirth Syntax Notation}}, with structures like

*{<list of valid alternatives>}, e.g. blerp {A,B,C}
*[<optional element>], e.g. blerp [-o [<output file>]]
*<something>... meaning repeat <something> as many times as you need

But the two Synopsis lines given do not have valid Wirth syntax; they randomly mix objects and syntactic characters, and the brackets and braces are not properly nested or paired.

The Description section provides an unhelpful summary that could apply to almost any Unix command. Processing input files (or output of other commands in a pipeline) is a generic function for Unix shell tools, as is specifying their behaviour with command line arguments, environment variables and flags. The text leaves to the reader's imagination what the program actually ''does'', and what behavior the various options modify, which gives maximum scope for humorous possibilities.

The options are in conventional alphabetical order, except that lower case is placed before upper case, and an em-dash is inserted between b and c.

{{w|Command-line_interface#Command-line_option|Command-line options}}, also known as flags, are typed after the program's name to change how the program runs. For example, a user of ''blerp'' might type:

<code>blerp -a -d -t -p "AVIGNON"</code>

According to the man page, this would run blerp in attack mode, piping its output to DEBUG.EXE, with tumble dry, and the true Pope set to "AVIGNON". In most cases, any number of flags can be used in any order, and flags can be followed by argument (such as "AVIGNON" in this example).

For a walkthrough of all possible flags see the '''[[#Table of flags|table of flags]]''' below.

Below the flags there is a ''see also'' list with other ludicrous program names (blirb, [http://www.urbandictionary.com/define.php?term=Blarb blarb] and [http://www.urbandictionary.com/define.php?term=Blorp blorp]), each followed by a number in parentheses. This is a common way to refer to a command in Unix environments, where the number denotes the documentation section the program is found in. This serves to disambiguate man pages with the same name, in this instance those for the blerp command (section 1, "General commands") and the blerp() C library function (section 3, "C library functions").

It is unknown which section the man page in this comic resides in. It looks like it could be in section 1, "General commands", which would make it self-referential. Section numbers only go up to 8, so blarb(51) is not a valid section number. The last blorp(501)(c)(3) is not a valid section number either, it is however a slightly covert reference to {{w|501(c)_organization#501.28c.29.283.29|501(c)(3)}} which is an organization that is {{w|Tax exemption|tax-exempt}}.

Then follows a bug report site. www.inaturalist.org is a site working to extend biological research, and the exact address given, http://www.inaturalist.org/taxa/47744-Hemiptera, points to the same page as http://www.inaturalist.org/taxa/Hemiptera. {{w|Hemiptera}} is the order classifying ''true bugs'', making it a good place to report any biological bugs discovered while running a program (Like the bees found without using -b.) Insects got into some early computers, causing them to malfunction, and hence computer malfunctions are often called "bugs".

Finally there is a "{{w|copyright}}" line which references several variously open-source content licenses, which is a recurring theme on xkcd (see [[225: Open Source]]). For instance, GPL references {{w|GNU General Public License}} and the (2) and (3+) refers to {{w|GNU_General_Public_License#Version_2|GPL 2}} and {{w|GNU_General_Public_License#Version_3|GPL 3 or higher}}. ''CC'' refers to {{w|creative commons}} where ''BY'' is the {{w|Creative_Commons_license#Types_of_licenses|type of license}}, ''5.0'' refers to the attribution and ''RV 41.0'' refers to revision 41.0. However there were no higher attribution than [https://creativecommons.org/licenses/by/4.0/legalcode 4.0] at the time of this comic's release. xkcd is released under [http://creativecommons.org/licenses/by-nc/2.5/ CC BY-NC 2.5] as can be seen at the bottom of the {{xkcd}}&nbsp;&nbsp;homepage. A few comics have been released under the [[:Category:CC-BY-SA comics|CC-BY-SA license]] or [http://creativecommons.org/licenses/by-sa/3.0/ 3.0]. BSD refers to {{w|BSD licenses}}, another [[:Category:BSD|recurring theme]] in xkcd. "Like Gecko" is a reference to a web browser user-agent string; modern user-agent strings include a [http://webaim.org/blog/user-agent-string-history/ lot of text designed] to allow browsers to masquerade as different browsers/renderers, and "(like Gecko)" is the standard text for a browser that wants to be treated as if it were {{w|Gecko (software)|Gecko}} while admitting, if you look closely, that it isn't really Gecko. This copyright line, which includes a lot of mashed-together text that might appear to match any of several different licenses, resembles a {{w|user agent}} string.

"Or best offer" is usually seen on a notice of a private sale, where it proclaims the intent to be flexible on asking price in the hope of expediting the sale, with a suggestion that the seller will sell to the highest bidder even if the offer is nowhere near the asking price. In the context of the comic, it suggest that the rights for the program are available for purchase by anyone who makes the "best" offer. Since the other licenses listed would allow free usage without incurring any royalty charge, it would be pointless to buy the rights to this program. It is possible to revoke the other licenses though. Perhaps the program's creator is suggesting the rights could be given to someone making him a different sort of offer, perhaps romantic or sexual?

In the title text there is a list with even more info, again with silly names like [http://blarbl.blogspot.dk/ blarbl] and [http://www.urbandictionary.com/define.php?term=birb birb]. Again there are section numbers. While writing about birb, and without bothering to close the brackets around (3), the writer breaks off to laugh at the reader, telling them that he is kidding and suggesting that they ''just Google it like a normal person''. To fix the fact that the writer didn’t close the parenthesis: ). The implication is that anyone trying to pick through a man page to find out what a program does is going the long way round, when it's much simpler to get Google to tell you.

Man pages were part of the subject of [[293: RTFM]], [[912: Manual Override]] and [[1343: Manuals]] and were mentioned in [[456: Cautionary]].

===Table of flags===
*There are 28 'defined' flags.
**Only these five letters are not used: l, m, w, x, z.
**j and k are used together as jk.
**The following seven capital letters are used: D, I, O, R, S, U, V.
***That makes it one capital letter for every lower case letter that is not used by itself.
**Finally the em dash "—" is used as the only non-letter character. Also the only that breaks the strict alphabetical sorting of the list, with lower case before upper case letters.
**As well as the general expansion of flag-use 'definitions', -f is explicitly featured in the first usage example of the Synopsis. See below.
**Additionally, either "-{}" or "- {}" is featured in the Synopsis's second usage example. This could indicate a flag of further type (an ill-defined set of further possibilities or ''literally'' a curly-bracket pair) or else specifies STDIN as a possible file input (and ''then'' ill-defined/curly-bracketted continuations of the parameter-listing).
{| class="wikitable"
!Flag!!Description!!Explanation
|-
| -a||ATTACK MODE||This sounds like a command for a robot or something similar. Strange for a command line program. Possibly this is designed to break something? Sounds as if you have to ''really'' know what you're doing to use this option. Could also be a reference to Yu-Gi-Oh or other similar games where a card can be played in "Attack Mode".
|-
| -b||SUPPRESS BEES||Nonsensical option. This is a word play, meaning either to suppress {{w|Bee|Bees}} (the insects) or the letter '''B'''. A possible implication is that running the program without this flag would somehow result in the user being attacked by bees. This is also a possible {{w|Discworld}} reference, as the ''{{W|Hex_(Discworld)#Structure_and_technology|long-term storage}}'' of the only recurring computer in the series, ''{{w|Hex (Discworld)|Hex}}'', is composed of a beehive. (Note that the actual computer runs on ants.) Another explanation is that there will be smoke (perhaps {{w|magic smoke}}?), which is used by beekeepers to suppress bees.
|-
| -—||FLAGS USE EM DASHES||Command line options (flags) typically use {{w|Hyphen|hyphens}} (short horizontal lines largely used within words). {{w|Dash#Em_dash|Em dashes}} (longer, with the same length as the letter "m") can't always be easily typed into a command line interface, so by invoking ''blerp'' with this flag you are intentionally making things difficult for yourself.

This may be a play on how a lot of commands accept both single-dash options, like -h for help, as well as double-dash options like --help also for help. In word processors, a double-dash (--) is often replaced with the longer em dash (—), making them kind of synonymous.

Also implies a paradox where if flags were to use em dashes, this flag would be invalid.
|-
| -c||COUNT NUMBER OF ARGUMENTS||Most likely not useful, but the only function of ''blerp'' whose behaviour is at all well defined, although there is no indication whether it would count duplicate flags or only distinct ones.
|-
| -d||PIPES OUTPUT TO DEBUG.EXE||{{w|DEBUG.EXE}} is the old 16-bit debugger that came with MS-DOS. On a Unix system it is much more likely that one would use the {{w|GNU Debugger}} (GDB). A debugger is usually called by calling the debugger with the program (or script) to be debugged as parameter.
{{w|Pipeline (Unix)|Piping}} in Unix means that the output of one program serves as input for another program.
|-
| -D||DEPRECATED||Many programs contain legacy options to avoid breaking scripts that use them. While the option should still work, the documentation is changed to say "deprecated" to discourage further use. Eventually such options usually get removed. (However, given the nature of this comic, it's likely that -D has always stood for "deprecated".)
|-
| -e||EXECUTE SOMETHING||Vague. Also a possible pun on a kill-switch.
|-
| -f||FUN MODE||Strange and slightly ominous, given some of the other options. How does the program know what the user would consider fun? Perhaps ''blerp'' is sentient, and has its own concept of "fun". See under -O.
The presence of an -f and then "FLAGS" in the usage Synopsis suggests that this flag can be used to flag that ''subsequent'' command flags are explicitly under the FUN MODE context, but with nothing to prevent -f (also?) being a standalone flag in the general ARGS (argument options, including flag parameters) ''or'' being further included in such a FUN MODE's hierarchical list of flags. This is just a further ambiguity to the Synopsis format, where it is often explicitly expanded into separate interpretations where the program has a complex but defined-in expectation of how to deal with such varied parsing possibilities.
|-
| -g||USE GOOGLE||As an actual program flag, a bit hackjob-ish, but it is possible it is telling the user to use Google to find out what this tag does. Or, the program might actually use Google functionality (e.g. a code library online) or even simply the search mask to achieve the filtering it is supposed to do. The fact that this is optional suggests that there is also a 'native' implementation that does not use Google.
Possible reference to the title text, which could mean that the title text is telling the user to use this flag.
|-
| -h||CHECK WHETHER INPUT HALTS||The {{w|Halting problem}} is the problem of determining, from a description of an arbitrary computer program and an input, whether the program will finish running or continue to run forever. {{w|Alan Turing}} proved in 1936 that a general algorithm to solve the halting problem for all possible program-input pairs cannot exist. Halting problem also featured in the comic [[1266: Halting Problem]].

Many Unix and Linux commands reserve -h for help, so using it for a different function is non-standard. The ''shutdown'' command is a real example of an exception: it uses -h to cause the computer to halt.
|-
| -i||IGNORE CASE (LOWER)||Usually, ignoring case means that a program will run without differentiating between upper- and lowercase. This flag suggests that blerp will run ignoring all the lowercase characters completely, or ignoring all the uppercase characters with the next flag "-I". Alternatively it will ignore the case of all lower case characters, but not upper case ones. Or perhaps this option makes the program ignore the case of flags like -i and -I...
|-
| -I||IGNORE CASE (UPPER)||See above. Also possible that all text is converted to upper case, or that upper-case requirements only are ignored.
|-
| -jk||KIDDING||A common acronym for [http://www.urbandictionary.com/define.php?term=jk Just Kidding], not usually a program flag! Also note that standard behavior of Unix command line options is that a single "-" can be followed by multiple one-letter options, making -jk equivalent to -j -k. Perhaps this is a reference to the -WhatIf flag provided by many programs written in {{w|powershell}}. Some UNIX programs do offer a "simulation mode" before important, irreversible operations, such as the "-n" switch of mke2fs.
|-
| -n||BEHAVIOR NOT DEFINED||Who would ever knowingly run a program, knowing that {{w|Nondeterministic programming|its behaviour was non-deterministic or random}}? Doing such a thing seems potentially sinister. (Possible debug/unstable feature flag.)
|-
| -o||OVERWRITE||Standard program flag, usually meaning that the program will overwrite a file rather than make a new one when data is output. But the text does not indicate ''what'' the program will overwrite, it could be anything. May work strangely with -d.
|-
| -O||OPPOSITE DAY||Strange flag, a reference to {{w|Opposite Day}}. Perhaps indicates that it would make all other flags have the opposite effects as usual. If so, a lot of strange things would happen, especially with -b, -e, -f, -jk, -O, -S, and -y. On the other hand, it may simply indicate that absent flags are treated as if they were present and vice versa.
|-
| -p||SET TRUE POPE; ACCEPTS "ROME" OR "AVIGNON"||This refers to a {{w|Western_Schism|historical schism}} in the {{w|Catholic Church}}. In the 14th century, the Pope briefly ruled from Avignon, France, instead of Rome. After the Papacy was returned to Rome in 1377, the Church split (the so-called Western Schism) as not everyone accepted the move or the authority of the Pope who ordered it. This flag apparently allows the user to select a preferred Pope. A possible feature request for ''blerp'' would be to allow "PISA". It is the second time this week that Popes have been mentioned, last time was two comics before in [[1690: Time-Tracking Software]] regarding the Pope's sexual activity.
|-
| -q||QUIET MODE; OUTPUT IS PRINTED TO STDOUT INSTEAD OF BEING SPOKEN ALOUD||In most cases, a program will output basic information to the console, and running it in quiet mode will make it run without outputting anything. Blerp, on the other hand, apparently outputs information through audio, and the quiet flag causes it to run like a normal program. "STDOUT" is short for "standard output".
|-
| -r||RANDOMIZE ARGUMENTS||Pointless and possibly damaging. Presumably the randomization takes the form of any flag randomly causing the behavior of another. This would perhaps be similar in effect to the -n flag.
|-
| -R||RUN RECURSIVELY ON <nowiki>http://*</nowiki>||The star (*) symbol is often used as a wildcard to match any string of characters. "<nowiki>http://*</nowiki>" suggests that blerp will be run recursively on every (unsecured) webpage on the internet. Programming requirements that might make this a valid thing to want to do are ominous.
|-
| -s||FOLLOW SYMBOLIC LINKS SYMBOLICALLY||A {{w|symbolic link}} is a filesystem feature that allows the creation of "fake" files which when accessed redirect to another file path. Many commands offer an option to follow filesystem links and operate on the actual file rather than the fake pointer; this option however seems to suggest that it will only politely pretend to do so.
|-
| -S||STEALTH MODE||Similar to -a, in that it sounds more like an option for some kind of robot. In this mode it appears the program will attempt to make sneaky changes without drawing any attention to itself.
|-
| -t||TUMBLE DRY||Perhaps useful for a program that runs on a clothes dryer. Refers to [https://img1.etsystatic.com/000/0/5254504/il_570xN.184726893.jpg directions like these]. Many clothing items are marked "do not tumble dry" in the care instructions, but this would be extremely difficult to make relevant to a program. Given the other flags, this may be less nonsensical than it would first appear. This flag could also be a reference to the dry-run flags that are sometimes available to make command line tools do a simulation run without making any actual modifications to the system.
|-
| -u||UTF-8 MODE; OTHERWISE DEFAULTS TO ANSEL||{{w|ANSEL}} is an obscure character encoding introduced in 1985. It extends ASCII by adding 63 new characters, including 29 combining diacritics. Since most hardware in the 1980s could not handle combining diacritics, it was never popular. Using ANSEL as a default would be strange, as most terminals will not know how to decode it, and will provide incorrect characters for anything beyond ASCII. By comparison, UTF-8 is a standard text encoding supported by almost all modern systems. The problem with using different modes (where the original was also UTF-8) is shown in the title text of [[1683: Digital Data]].
|-
| -U||UPDATE (DEFAULT: FACEBOOK)||Update usually refers to replacing an old software with a newer version. The default here suggests posting a status update to Facebook, sourcing an update from Facebook, or updating Facebook itself.
|-
| -v||VERBOSE; ALIAS TO find / -exec cat {}||Almost standard flag, in ordinary programs the opposite of -q - instead of silencing output, it generates more, usually to help with debugging. For ''blerp'', this flag gets replaced with a command that prints the contents of all files in the filesystem tree. However, it will never complete, as certain device files never end (/dev/urandom contains random bytes). In any case, the "find" command is missing <code>\;</code> and will not run, instead complaining <code>find: missing argument to `-exec'</code> .
|-
| -V||SET VERSION NUMBER||Many programs will have a flag to view their version number. This flag ''changes'' the version number instead. Version number should only be changed when the program is updated (because it's used for distinguishing which edition of a program you have), so manually changing the version number like this is strange and potentially damaging.
|-
| -y||YIKES||{{Wiktionary|yikes}} is an interjection which can express fear or empathy with unpleasant or undesirable circumstances. It is unclear how this would influence the program.
|}

==Transcript==
:[A terminal screen; the background is black and the text is white.]
<div style="background-color:black;color:white;white-space:pre-wrap;font-family:monospace;padding: 0 2em;max-width:50em;">
;NAME
:blerp
;SYNOPSIS
:blerp {[ OPTION | ARGS ]...[ ARGS ... -f [FLAGS] ...}
:blerp {... DIRECTORY ... URL | BLERP} OPTIONS ] -{}
;DESCRIPTION
:blerp FILTERS LOCAL OR REMOTE FILES OR RESOURCES USING PATTERNS DEFINED BY ARGUMENTS AND ENVIRONMENT VARIABLES. THIS BEHAVIOR CAN BE ALTERED BY VARIOUS FLAGS.
;OPTIONS
:-a      ATTACK MODE
:-b      SUPPRESS BEES
:-—      FLAGS USE EM DASHES
:-c      COUNT NUMBER OF ARGUMENTS
:-d      PIPES OUTPUT TO DEBUG.EXE
:-D      DEPRECATED
:-e      EXECUTE SOMETHING
:-f      FUN MODE
:-g      USE GOOGLE
:-h      CHECK WHETHER INPUT HALTS
:-i      IGNORE CASE (LOWER)
:-I      IGNORE CASE (UPPER)
:-jk     KIDDING
:-n      BEHAVIOR NOT DEFINED
:-o      OVERWRITE
:-O      OPPOSITE DAY
:-p      SET TRUE POPE; ACCEPTS "ROME" OR "AVIGNON"
:-q      QUIET MODE; OUTPUT IS PRINTED TO STDOUT INSTEAD OF BEING SPOKEN ALOUD
:-r      RANDOMIZE ARGUMENTS
:-R      RUN RECURSIVELY ON <nowiki>http://*</nowiki>
:-s      FOLLOW SYMBOLIC LINKS SYMBOLICALLY
:-S      STEALTH MODE
:-t      TUMBLE DRY
:-u      UTF-8 MODE; OTHERWISE DEFAULTS TO ANSEL
:-U      UPDATE (DEFAULT: FACEBOOK)
:-v      VERBOSE; ALIAS TO find / -exec cat {}
:-V      SET VERSION NUMBER
:-y      YIKES
;SEE ALSO
:blerp(1), blerp(3), blirb(8), blarb(51) blorp(501)(c)(3)
;BUG REPORTS
:<nowiki>http://www.inaturalist.org/taxa/47744-Hemiptera</nowiki>
;COPYRIGHT
:GPL(2)(3+) CC-BY/5.0 RV 41.0 LIKE GECKO/BSD 4(2) OR BEST OFFER
</div>

==Trivia==
Actual UNIX manpages exist on some systems which are written in a similar, nonsensical style to these.
Manual pages distributed for the ''<n>fun'' sections describe similarly humorous "commands" with unusual options.
On some systems, these manual pages are available in funny-manpages or asr-manpages packages.

{{comic discussion}}

[[Category:Programming]]
[[Category:Computers]]
[[Category:BSD]]
[[Category:Bees]]
[[Category:Man pages]]
[[Category:Scientific research]]