From 3680c4667f1a47000c0152ca34bc3af7c41825ac Mon Sep 17 00:00:00 2001 From: Martin Afanasjew Date: Sun, 17 Apr 2016 05:33:21 +0200 Subject: man: replace split header/footer with ERB template --- Library/Homebrew/cmd/man.rb | 14 +- Library/Homebrew/manpages/brew.1.md.erb | 275 ++++++++++++++++++++++++++++++++ Library/Homebrew/manpages/footer.1.md | 236 --------------------------- Library/Homebrew/manpages/header.1.md | 38 ----- 4 files changed, 281 insertions(+), 282 deletions(-) create mode 100644 Library/Homebrew/manpages/brew.1.md.erb delete mode 100644 Library/Homebrew/manpages/footer.1.md delete mode 100644 Library/Homebrew/manpages/header.1.md (limited to 'Library') diff --git a/Library/Homebrew/cmd/man.rb b/Library/Homebrew/cmd/man.rb index 112eff60d..164eca9b1 100644 --- a/Library/Homebrew/cmd/man.rb +++ b/Library/Homebrew/cmd/man.rb @@ -1,4 +1,5 @@ require "formula" +require "erb" module Homebrew SOURCE_PATH = HOMEBREW_LIBRARY_PATH/"manpages" @@ -38,22 +39,19 @@ module Homebrew end def build_man_page - header = (SOURCE_PATH/"header.1.md").read - footer = (SOURCE_PATH/"footer.1.md").read + template = (SOURCE_PATH/"brew.1.md.erb").read commands = Pathname.glob("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}"). sort_by { |source_file| source_file.basename.sub(/\.(rb|sh)$/, "") }. map { |source_file| - source_file.read. - split("\n"). + source_file.read.lines. grep(/^#:/). map { |line| line.slice(2..-1) }. - join("\n") + join }. - reject { |s| s.strip.empty? }. - join("\n\n") + reject { |s| s.strip.empty? } - header + commands + footer + ERB.new(template, nil, ">").result(binding) end def convert_man_page(markup, target) diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb new file mode 100644 index 000000000..5fc1d7e6d --- /dev/null +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -0,0 +1,275 @@ +brew(1) -- The missing package manager for OS X +=============================================== + +## SYNOPSIS + +`brew` `--version`
+`brew` [`--verbose`|`-v`] [] [] ... + +## DESCRIPTION + +Homebrew is the easiest and most flexible way to install the UNIX tools Apple +didn't include with OS X. + +## ESSENTIAL COMMANDS + +For the full command list, see the [COMMANDS][] section. + +With `--verbose` or `-v`, many commands print extra debugging information. Note that these flags should only appear after a command. + + * `install` : + Install . + + * `remove` : + Uninstall . + + * `update`: + Fetch the newest version of Homebrew from GitHub using `git`(1). + + * `list`: + List all installed formulae. + + * `search` |`/``/`: + Perform a substring search of formula names for . If is + surrounded with slashes, then it is interpreted as a regular expression. + The search for is extended online to some popular taps. + If no search term is given, all locally available formulae are listed. + +## COMMANDS + +<%= commands.join("\n") %> + + * `--cache`: + Display Homebrew's download cache. See also `HOMEBREW_CACHE`. + + * `--cache` : + Display the file or directory used to cache . + + * `--cellar`: + Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if + that directory doesn't exist, `$(brew --repository)/Cellar`. + + * `--cellar` : + Display the location in the cellar where would be installed, + without any sort of versioned directory as the last path. + + * `--env`: + Show a summary of the Homebrew build environment. + + * `--prefix`: + Display Homebrew's install path. *Default:* `/usr/local` + + * `--prefix` : + Display the location in the cellar where is or would be installed. + + * `--repository`: + Display where Homebrew's `.git` directory is located. For standard installs, + the `prefix` and `repository` are the same directory. + + * `--repository` `/`: + Display where tap `/`'s directory is located. + + * `--version`: + Print the version number of brew to standard error and exit. + +## EXTERNAL COMMANDS + +Homebrew, like `git`(1), supports external commands. These are executable +scripts that reside somewhere in the `PATH`, named `brew-` or +`brew-``.rb`, which can be invoked like `brew` . This allows you +to create your own commands without modifying Homebrew's internals. + +Instructions for creating your own commands can be found in the docs: + + +## SPECIFYING FORMULAE + +Many Homebrew commands accept one or more arguments. These arguments +can take several different forms: + + * The name of a formula: + e.g. `git`, `node`, `wget`. + + * The fully-qualified name of a tapped formula: + Sometimes a formula from a tapped repository may conflict with one in `Homebrew/homebrew`. + You can still access these formulae by using a special syntax, e.g. + `homebrew/dupes/vim` or `homebrew/versions/node4`. + + * An arbitrary URL: + Homebrew can install formulae via URL, e.g. + `https://raw.github.com/Homebrew/homebrew-core/master/Formula/git.rb`. + The formula file will be cached for later use. + +## ENVIRONMENT + + * `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`: + When using the `S3` download strategy, Homebrew will look in + these variables for access credentials (see + + to retrieve these access credentials from AWS). If they are not set, + the `S3` download strategy will download with a public + (unsigned) URL. + + * `BROWSER`: + If set, and `HOMEBREW_BROWSER` is not, use `BROWSER` as the web browser + when opening project homepages. + + * `EDITOR`: + If set, and `HOMEBREW_EDITOR` and `VISUAL` are not, use `EDITOR` as the text editor. + + * `GIT`: + When using Git, Homebrew will use `GIT` if set, + a Homebrew-built Git if installed, or the system-provided binary. + + Set this to force Homebrew to use a particular git binary. + + * `HOMEBREW_BOTTLE_DOMAIN`: + If set, instructs Homebrew to use the given URL as a download mirror for bottles. + + * `HOMEBREW_BROWSER`: + If set, uses this setting as the browser when opening project homepages, + instead of the OS default browser. + + * `HOMEBREW_BUILD_FROM_SOURCE`: + If set, instructs Homebrew to compile from source even when a formula + provides a bottle. This environment variable is intended for use by + Homebrew developers. Please do not file issues if you encounter errors when + using this environment variable. + + * `HOMEBREW_CACHE`: + If set, instructs Homebrew to use the given directory as the download cache. + + *Default:* `~/Library/Caches/Homebrew` if it exists; otherwise, + `/Library/Caches/Homebrew`. + + * `HOMEBREW_CURL_VERBOSE`: + If set, Homebrew will pass `--verbose` when invoking `curl`(1). + + * `HOMEBREW_DEBUG`: + If set, any commands that can emit debugging information will do so. + + * `HOMEBREW_DEBUG_INSTALL`: + When `brew install -d` or `brew install -i` drops into a shell, + `HOMEBREW_DEBUG_INSTALL` will be set to the name of the formula being + brewed. + + * `HOMEBREW_DEBUG_PREFIX`: + When `brew install -d` or `brew install -i` drops into a shell, + `HOMEBREW_DEBUG_PREFIX` will be set to the target prefix in the Cellar + of the formula being brewed. + + * `HOMEBREW_DEVELOPER`: + If set, Homebrew will print warnings that are only relevant to Homebrew + developers (active or budding). + + * `HOMEBREW_EDITOR`: + If set, Homebrew will use this editor when editing a single formula, or + several formulae in the same directory. + + *Note:* `brew edit` will open all of Homebrew as discontinuous files and + directories. TextMate can handle this correctly in project mode, but many + editors will do strange things in this case. + + * `HOMEBREW_GITHUB_API_TOKEN`: + A personal access token for the GitHub API, which you can create at + . If set, GitHub will allow you a + greater number of API requests. See + for more information. + Homebrew uses the GitHub API for features such as `brew search`. + + *Note:* Homebrew doesn't require permissions for any of the scopes. + + * `HOMEBREW_LOGS`: + If set, Homebrew will use the given directory to store log files. + + * `HOMEBREW_MAKE_JOBS`: + If set, instructs Homebrew to use the value of `HOMEBREW_MAKE_JOBS` as + the number of parallel jobs to run when building with `make`(1). + + *Default:* the number of available CPU cores. + + * `HOMEBREW_NO_ANALYTICS`: + If set, Homebrew will not send analytics. See: + + *Note:* Homebrew currently disables analytics by default. + + * `HOMEBREW_NO_EMOJI`: + If set, Homebrew will not print the `HOMEBREW_INSTALL_BADGE` on a + successful build. + + *Note:* Homebrew will only try to print emoji on Lion or newer. + + * `HOMEBREW_NO_INSECURE_REDIRECT`: + If set, Homebrew will not permit redirects from secure HTTPS + to insecure HTTP. + + While ensuring your downloads are fully secure, this is likely + to cause from-source Sourceforge & GNOME based formulae + to fail to download. + + Apache formulae are currently unaffected by this variable and + can redirect to plaintext. + + * `HOMEBREW_NO_GITHUB_API`: + If set, Homebrew will not use the GitHub API for e.g searches or + fetching relevant issues on a failed install. + + * `HOMEBREW_INSTALL_BADGE`: + Text printed before the installation summary of each successful build. + Defaults to the beer emoji. + + * `HOMEBREW_SVN`: + When exporting from Subversion, Homebrew will use `HOMEBREW_SVN` if set, + a Homebrew-built Subversion if installed, or the system-provided binary. + + Set this to force Homebrew to use a particular `svn` binary. + + * `HOMEBREW_TEMP`: + If set, instructs Homebrew to use `HOMEBREW_TEMP` as the temporary directory + for building packages. This may be needed if your system temp directory and + Homebrew Prefix are on different volumes, as OS X has trouble moving + symlinks across volumes when the target does not yet exist. + + This issue typically occurs when using FileVault or custom SSD + configurations. + + * `HOMEBREW_VERBOSE`: + If set, Homebrew always assumes `--verbose` when running commands. + + * `VISUAL`: + If set, and `HOMEBREW_EDITOR` is not, use `VISUAL` as the text editor. + +## USING HOMEBREW BEHIND A PROXY + +Homebrew uses several commands for downloading files (e.g. `curl`, `git`, `svn`). +Many of these tools can download via a proxy. It's common for these tools +to read proxy parameters from environment variables. + +For the majority of cases setting `http_proxy` is enough. You can set this in +your shell profile, or you can use it before a brew command: + + http_proxy=http://: brew install foo + +If your proxy requires authentication: + + http_proxy=http://:@: brew install foo + +## SEE ALSO + +Homebrew Documentation: + +`git`(1), `git-log`(1) + +## AUTHORS + +Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Martin Afanasjew, Dominyk Tiller, Tim Smith and Alex Dunn. + +Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell. + +## BUGS + +See our issues on GitHub: + + * Homebrew/brew + + * Homebrew/homebrew-core diff --git a/Library/Homebrew/manpages/footer.1.md b/Library/Homebrew/manpages/footer.1.md deleted file mode 100644 index 5ff6656a7..000000000 --- a/Library/Homebrew/manpages/footer.1.md +++ /dev/null @@ -1,236 +0,0 @@ - - - * `--cache`: - Display Homebrew's download cache. See also `HOMEBREW_CACHE`. - - * `--cache` : - Display the file or directory used to cache . - - * `--cellar`: - Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if - that directory doesn't exist, `$(brew --repository)/Cellar`. - - * `--cellar` : - Display the location in the cellar where would be installed, - without any sort of versioned directory as the last path. - - * `--env`: - Show a summary of the Homebrew build environment. - - * `--prefix`: - Display Homebrew's install path. *Default:* `/usr/local` - - * `--prefix` : - Display the location in the cellar where is or would be installed. - - * `--repository`: - Display where Homebrew's `.git` directory is located. For standard installs, - the `prefix` and `repository` are the same directory. - - * `--repository` `/`: - Display where tap `/`'s directory is located. - - * `--version`: - Print the version number of brew to standard error and exit. - -## EXTERNAL COMMANDS - -Homebrew, like `git`(1), supports external commands. These are executable -scripts that reside somewhere in the `PATH`, named `brew-` or -`brew-``.rb`, which can be invoked like `brew` . This allows you -to create your own commands without modifying Homebrew's internals. - -Instructions for creating your own commands can be found in the docs: - - -## SPECIFYING FORMULAE - -Many Homebrew commands accept one or more arguments. These arguments -can take several different forms: - - * The name of a formula: - e.g. `git`, `node`, `wget`. - - * The fully-qualified name of a tapped formula: - Sometimes a formula from a tapped repository may conflict with one in `Homebrew/homebrew`. - You can still access these formulae by using a special syntax, e.g. - `homebrew/dupes/vim` or `homebrew/versions/node4`. - - * An arbitrary URL: - Homebrew can install formulae via URL, e.g. - `https://raw.github.com/Homebrew/homebrew-core/master/Formula/git.rb`. - The formula file will be cached for later use. - -## ENVIRONMENT - - * `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`: - When using the `S3` download strategy, Homebrew will look in - these variables for access credentials (see - - to retrieve these access credentials from AWS). If they are not set, - the `S3` download strategy will download with a public - (unsigned) URL. - - * `BROWSER`: - If set, and `HOMEBREW_BROWSER` is not, use `BROWSER` as the web browser - when opening project homepages. - - * `EDITOR`: - If set, and `HOMEBREW_EDITOR` and `VISUAL` are not, use `EDITOR` as the text editor. - - * `GIT`: - When using Git, Homebrew will use `GIT` if set, - a Homebrew-built Git if installed, or the system-provided binary. - - Set this to force Homebrew to use a particular git binary. - - * `HOMEBREW_BOTTLE_DOMAIN`: - If set, instructs Homebrew to use the given URL as a download mirror for bottles. - - * `HOMEBREW_BROWSER`: - If set, uses this setting as the browser when opening project homepages, - instead of the OS default browser. - - * `HOMEBREW_BUILD_FROM_SOURCE`: - If set, instructs Homebrew to compile from source even when a formula - provides a bottle. This environment variable is intended for use by - Homebrew developers. Please do not file issues if you encounter errors when - using this environment variable. - - * `HOMEBREW_CACHE`: - If set, instructs Homebrew to use the given directory as the download cache. - - *Default:* `~/Library/Caches/Homebrew` if it exists; otherwise, - `/Library/Caches/Homebrew`. - - * `HOMEBREW_CURL_VERBOSE`: - If set, Homebrew will pass `--verbose` when invoking `curl`(1). - - * `HOMEBREW_DEBUG`: - If set, any commands that can emit debugging information will do so. - - * `HOMEBREW_DEBUG_INSTALL`: - When `brew install -d` or `brew install -i` drops into a shell, - `HOMEBREW_DEBUG_INSTALL` will be set to the name of the formula being - brewed. - - * `HOMEBREW_DEBUG_PREFIX`: - When `brew install -d` or `brew install -i` drops into a shell, - `HOMEBREW_DEBUG_PREFIX` will be set to the target prefix in the Cellar - of the formula being brewed. - - * `HOMEBREW_DEVELOPER`: - If set, Homebrew will print warnings that are only relevant to Homebrew - developers (active or budding). - - * `HOMEBREW_EDITOR`: - If set, Homebrew will use this editor when editing a single formula, or - several formulae in the same directory. - - *Note:* `brew edit` will open all of Homebrew as discontinuous files and - directories. TextMate can handle this correctly in project mode, but many - editors will do strange things in this case. - - * `HOMEBREW_GITHUB_API_TOKEN`: - A personal access token for the GitHub API, which you can create at - . If set, GitHub will allow you a - greater number of API requests. See - for more information. - Homebrew uses the GitHub API for features such as `brew search`. - - *Note:* Homebrew doesn't require permissions for any of the scopes. - - * `HOMEBREW_LOGS`: - If set, Homebrew will use the given directory to store log files. - - * `HOMEBREW_MAKE_JOBS`: - If set, instructs Homebrew to use the value of `HOMEBREW_MAKE_JOBS` as - the number of parallel jobs to run when building with `make`(1). - - *Default:* the number of available CPU cores. - - * `HOMEBREW_NO_ANALYTICS`: - If set, Homebrew will not send analytics. See: - - *Note:* Homebrew currently disables analytics by default. - - * `HOMEBREW_NO_EMOJI`: - If set, Homebrew will not print the `HOMEBREW_INSTALL_BADGE` on a - successful build. - - *Note:* Homebrew will only try to print emoji on Lion or newer. - - * `HOMEBREW_NO_INSECURE_REDIRECT`: - If set, Homebrew will not permit redirects from secure HTTPS - to insecure HTTP. - - While ensuring your downloads are fully secure, this is likely - to cause from-source Sourceforge & GNOME based formulae - to fail to download. - - Apache formulae are currently unaffected by this variable and - can redirect to plaintext. - - * `HOMEBREW_NO_GITHUB_API`: - If set, Homebrew will not use the GitHub API for e.g searches or - fetching relevant issues on a failed install. - - * `HOMEBREW_INSTALL_BADGE`: - Text printed before the installation summary of each successful build. - Defaults to the beer emoji. - - * `HOMEBREW_SVN`: - When exporting from Subversion, Homebrew will use `HOMEBREW_SVN` if set, - a Homebrew-built Subversion if installed, or the system-provided binary. - - Set this to force Homebrew to use a particular `svn` binary. - - * `HOMEBREW_TEMP`: - If set, instructs Homebrew to use `HOMEBREW_TEMP` as the temporary directory - for building packages. This may be needed if your system temp directory and - Homebrew Prefix are on different volumes, as OS X has trouble moving - symlinks across volumes when the target does not yet exist. - - This issue typically occurs when using FileVault or custom SSD - configurations. - - * `HOMEBREW_VERBOSE`: - If set, Homebrew always assumes `--verbose` when running commands. - - * `VISUAL`: - If set, and `HOMEBREW_EDITOR` is not, use `VISUAL` as the text editor. - -## USING HOMEBREW BEHIND A PROXY - -Homebrew uses several commands for downloading files (e.g. `curl`, `git`, `svn`). -Many of these tools can download via a proxy. It's common for these tools -to read proxy parameters from environment variables. - -For the majority of cases setting `http_proxy` is enough. You can set this in -your shell profile, or you can use it before a brew command: - - http_proxy=http://: brew install foo - -If your proxy requires authentication: - - http_proxy=http://:@: brew install foo - -## SEE ALSO - -Homebrew Documentation: - -`git`(1), `git-log`(1) - -## AUTHORS - -Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Martin Afanasjew, Dominyk Tiller, Tim Smith and Alex Dunn. - -Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell. - -## BUGS - -See our issues on GitHub: - - * Homebrew/brew - - * Homebrew/homebrew-core diff --git a/Library/Homebrew/manpages/header.1.md b/Library/Homebrew/manpages/header.1.md deleted file mode 100644 index 7caf028db..000000000 --- a/Library/Homebrew/manpages/header.1.md +++ /dev/null @@ -1,38 +0,0 @@ -brew(1) -- The missing package manager for OS X -=============================================== - -## SYNOPSIS - -`brew` `--version`
-`brew` [`--verbose`|`-v`] [] [] ... - -## DESCRIPTION - -Homebrew is the easiest and most flexible way to install the UNIX tools Apple -didn't include with OS X. - -## ESSENTIAL COMMANDS - -For the full command list, see the [COMMANDS][] section. - -With `--verbose` or `-v`, many commands print extra debugging information. Note that these flags should only appear after a command. - - * `install` : - Install . - - * `remove` : - Uninstall . - - * `update`: - Fetch the newest version of Homebrew from GitHub using `git`(1). - - * `list`: - List all installed formulae. - - * `search` |`/``/`: - Perform a substring search of formula names for . If is - surrounded with slashes, then it is interpreted as a regular expression. - The search for is extended online to some popular taps. - If no search term is given, all locally available formulae are listed. - -## COMMANDS -- cgit v1.2.3