The JavaScript Manual

JavaScript deserves good documentation, this aims to be the canonical manual.

I believe that UNIX (realistically Linux/BSD/GNU) is practically everywhere because of its remarkable documentation. Without concise, accurate, consistent, and detailed man pages, the software we use today would simply not exist.

I don't believe that the JavaScript language and ecosystem has a single, cohesive artifact similar to the Linux User's Manual, the Unix First Edition Manuals, or the OpenBSD Documentation.

This work aims to be a similar style of manual, which serves as a source of truth for JavaScript programmers.

Installing

Windows

Automated installation not yet supported on Windows

MacOS

Run: make install

Note: this places man files with a prefix of /usr/local (to /usr/local, to use an alternate prefix, run make install PREFIX=/my/path/to/prefix

If you would like to pl

Linux

Automated installation not yet supported on Linux

Usage

After installation, you should be able to invoke man via man Array#sort or man Array.prototype.sort) to view the man pages.

To search for man pages by their name, use the whatis utility, for example:

$ whatis concat
Array#concat, Array.prototype.concat(3js) - join arrays together
String#concat, String.prototype.concat(3js) - join strings together

To search for man pages by their name or description, use the apropos utility, for example:

$ apropos locale
String#localeCompare, String.prototype.localeCompare(3js) - compare strings using a locale
String#toLocaleLowerCase, String.prototype.toLocaleLowerCase(3js) - make string lowercase according to a desired locale
String#toLocaleUpperCase, String.prototype.toLocaleUpperCase(3js) - make string uppercase according to a desired locale

Building

These manual pages are written using a custom text-document-like markup language. This custom markup language is compiled to mdoc format for man pages and html for browser viewing.

Building requires python3 and the dependencies in requirements.txt. To install the dependencies in a virtual environment, run:

1. python3 -mvenv .venv
2. .venv/bin/pip install -r requirements.txt

Run make to format the txt pages to man, mdoc, and html within the build/* directories.

To build, you'll need the mandoc program, which can be found at the mandocml ports page or the mandocml home page.

Authoring Notes

A page in the JavaScript Programmer's Manual should have the following sections:

• Date - The authored/last updated date (in format: Mar 11, 2016)
• Title - The fully qualified name of the documented item (i.e. Array.prototype.concat)
• Subtitle - A very brief description.
• Library - The language specification/library
• Signature (if a value/function) - A list of TypeScript type signatures. If needed, interfaces can be used to identify complex object structure.
• Description - A detailed description of the functionality. Include any error handling, gotchas, or other unusual characteristics in separate paragraphs.
• Returns (if a function) - A description of the qualities of the different return values.
• Examples (TBD, optional) - Short, well commented and named examples demonstrating use.
• Compatibility (TBD, optional) - Platform-specific implementation notes.
• See - A list of other related manual pages.

Typographic Considerations

• JavaScript variable and function names should be referenced in prose as [[variableName]]
• JavaScript literals or short expressions should be referenced in prose as <<"literal value">>
• JavaScript keywords should be referenced in prose as <<keyword>>
• TypeScript type names should be referenced in prose as TBD
• When referencing JavaScript functions in prose, add a () suffix
• In prose, use # as shorthand for .prototype. (i.e. String#charAt)
• When needing to identify the item referred to by this in prose, use the phrase "the original X". For example, when describing the modifying effect of Array#sort(), say "Calling Array#sort() will modify the original array". TBD (should it be underlined/annotated?)
• "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" written in all-caps should be interpreted as documented in RFC 2119

Copywriting Considerations

• Write in the present tense with direct and simple words.
• Avoid ambiguous language and idioms.
• Assume a non-native speaker of English will be reading this documentation.

Contributing

Contributions via github issues or pull requests will not be accepted.

If you would like to contribute, please contact me via email with the phrase "The JavaScript Manual" included in the subject line.

License

The JavaScript Manual by Sufian Rhazi is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/.

The JavaScript Manual is attributed to content by Mozilla Contributors, which is licensed under CC-BY-SA 2.5. This content is found at the URLs found within the LICENSE file.

The JavaScript Manual embeds highlight.js in the built html, which is licensed under the BSD 3-clause license and is Copyright (c) 2006, Ivan Sagalaev.

The JavaScript Manual embeds TypeScript annotations from the TypeScript standard library which is Copyright (c) Microsoft Corporation.