Fix Issue 17998 - Document Options for install.sh

download.dd

@@ -282,7 +282,9 @@ Macros:
         $(DIVC download_image, $1)
         $(DIVC download_paragraph, $(H3 $2) $3)
     )
-    INSTALL_SCRIPT=$(DIVC download_paragraph, $(H3 Install Script) $(PRE $(CODE $1)))
+    INSTALL_SCRIPT=$(DIVC download_paragraph,
+        $(H3 Install Script) $(LINK2 $(ROOT_DIR)install.html, Explain)
+        $(PRE $(CODE $1)))
     CONSOLE=$(PRE $(CODE $1))
     IMG=<img src="images/$1">
 

install.dd

@@ -0,0 +1,200 @@
+Ddoc
+
+
+$(D_S $(TITLE),
+
+$(H2 Introduction)
+
+The $(LINK2 https://dlang.org/install.sh, `dlang.org/install.sh`) script is the official D version manager for DMD, GDC and LDC on FreeBSD, Linux and macOS and provides a convenient way to fetch and install a D compiler without requiring administrative privileges nor external dependencies.
+Its features include:
+
+$(UL
+ $(LI Maintaining one or more portable compiler installations in the user's home directory (`~/dlang`))
+ $(LI Maintaining the latest stable version of $(LINK2 http://code.dlang.org/docs/commandline, `dub`))
+ $(LI Self-updating via `~/dlang/install.sh update`)
+ $(LI Supporting nested activation of compilers. Activating a compiler, will setup the `PATH`, `LIBRARY_PATH`, `LD_LIBRARY_PATH`, `DMD`, `DC`, and `PS1` environment variables. After activation, user's can revert those variables to their old values by invoking the `deactivate` command, added to current shell session, by the activation command.)
+ $(LI Supporting Fish shell, in addition to Bash-compatible shells.)
+ $(LI Verifying binary signatures via the $(LINK2 $(ROOT_DIR)gpg_keys.html,D keyring) (automatic if `gpg` is installed))
+ $(LI For `dmd`, installation of the following versions is supported:
+    $(UL
+        $(LI `dmd` - latest stable version)
+        $(LI `dmd-beta` - latest beta version)
+        $(LI `dmd-nightly` - the latest nightly release)
+        $(LI `dmd-<version>` - specific official release (including beta releases))
+        $(LI `dmd-branch` - experimental compiler branches)
+    )
+ )
+ $(LI For `ldc`, installation of the following versions is supported:
+    $(UL
+        $(LI `ldc` - latest stable version)
+        $(LI `ldc-beta` - latest beta version)
+        $(LI `ldc-<version>` - specific official release (including beta releases))
+    )
+ )
+ $(LI For `gdc`, installation of the following versions is supported:
+    $(UL
+        $(LI `gdc` - latest stable version)
+    )
+ )
+)
+
+$(H3 Content)
+
+$(UL
+    $(LI $(RELATIVE_LINK2 get, Downloading the installer))
+    $(LI $(RELATIVE_LINK2 usage, Usage))
+    $(UL
+        $(LI $(RELATIVE_LINK2 install, Installation))
+        $(LI $(RELATIVE_LINK2 uninstall, Uninstallation))
+        $(LI $(RELATIVE_LINK2 list, Listing available compilers))
+        $(LI $(RELATIVE_LINK2 update, Update))
+    )
+)
+
+$(H2 $(LNAME2 get, Downloading the installer))
+
+$(CONSOLE
+wget https://dlang.org/install.sh
+)
+
+If you want, you can directly invoke it:
+
+$(CONSOLE
+curl https://dlang.org/install.sh | bash -s
+)
+
+$(P If no argument are provided, the latest DMD compiler will be installed.)
+
+$(P The installer will also install a copy of itself to `~/dlang/install.sh`.)
+
+$(H2 $(LNAME2 usage, Usage))
+
+$(CONSOLE
+~/dlang/install.sh [&lt;command&gt;] [&lt;args&gt;]
+)
+
+$(UL
+    $(LI $(RELATIVE_LINK2 install, Installation))
+    $(LI $(RELATIVE_LINK2 uninstall, Uninstallation))
+    $(LI $(RELATIVE_LINK2 list, Listing available compilers))
+    $(LI $(RELATIVE_LINK2 update, Update))
+)
+
+$(H3 $(LNAME2 global_options, Global options))
+
+$(DL
+    $(DT
+        $(SWITCH $(SWNAME -p) $(SWNAME --path),
+            Changes the install location (default `~/dlang`))
+        $(SWITCH $(SWNAME -v),
+            Activates more verbose output)
+        $(SWITCH $(SWNAME -h),
+            Displays a help page)
+    )
+)
+
+$(H3 $(LNAME2 install, Install))
+
+$(CONSOLE
+~/dlang/install.sh install &lt;compiler&gt;
+)
+
+Download and install a D compiler.
+By default the latest release of the DMD compiler is selected.
+
+$(H4 Options)
+
+$(DL
+    $(DT
+        $(SWITCH $(SWNAME -a) $(SWNAME --active),
+            Only prints the path to the activate script)
+        $(SWITCH $(SWNAME dmd|ldc|gdc),
+            Installs the latest version of a compiler)
+        $(SWITCH $(SWNAME dmd|ldc|gdc-&lt;version&gt;),
+            Installs a specific version of a compiler (e.g. dmd-2.071.1, ldc-1.1.0-beta2))
+        $(SWITCH $(SWNAME dmd|ldc-beta),
+            Installs the latest beta version of a compiler)
+        $(SWITCH $(SWNAME dmd-nightly),
+            Installs DMD nightly)
+        $(SWITCH $(SWNAME dmd-20170-02-10),
+            Installs specific DMD nightly)
+    )
+)
+
+$(EXAMPLES
+~/dlang/install.sh
+~/dlang/install.sh dmd
+~/dlang/install.sh install dmd
+~/dlang/install.sh install dmd-2.071.1
+~/dlang/install.sh install ldc-1.1.0-beta2
+)
+
+$(P Once a compiler can be activated for the current session:)
+
+Run the respective `activate` script in your shell to use a compiler by default:
+
+$(CONSOLE
+source ~/dlang/&lt;installed-compiler&gt;/activate
+)
+
+This will setup `PATH`, `LIBRARY_PATH`, `LD_LIBRARY_PATH`, `DMD`, `DC`, and `PS1`.
+It's also possible to combine this into one command:
+
+$(CONSOLE
+source $(~/dlang/install.sh dmd -a)
+)
+
+The activated compiler can also be removed from the current session by restoring
+the previous environment:
+
+$(CONSOLE
+deactivate
+)
+
+Alternatively, it is also possible to directly use a compiler by calling its
+binary directly.
+Note that the exact path varies between the compiler vendors:
+
+$(CONSOLE
+~/dlang/&lt;installed-dmd-compiler&gt;/bin64/dmd
+~/dlang/&lt;installed-ldc-compiler&gt;/ldc2
+)
+
+
+$(H3 $(LNAME2 uninstall, Uninstall))
+
+Uninstall a D compiler
+
+$(CONSOLE
+~/dlang/install.sh uninstall &lt;compiler&gt;
+)
+
+$(EXAMPLES
+~/dlang/install.sh uninstall dmd
+/install.sh uninstall dmd-2.071.1
+/install.sh uninstall ldc-1.1.0-beta2
+)
+
+$(H3 $(LNAME2 list, List))
+
+List all installed D compilers.
+
+$(CONSOLE
+~/dlang/install.sh list
+)
+
+$(H3 $(LNAME2 update, Update))
+
+Update the dlang installer itself.
+
+$(CONSOLE
+~/dlang/install.sh update
+)
+
+)
+Macros:
+    TITLE=Install.sh script
+    SWNAME=$(LNAME2 switch$1, $(B $1))
+    SWLINK=$(LINK2 #switch$1, $(B $1))
+    SWITCH=$(DT $1)$(DD $+)
+    EXAMPLES=$(H4 Examples)$(CONSOLE $0)

posix.mak

@@ -351,7 +351,7 @@ PAGES_ROOT=$(SPEC_ROOT) 404 acknowledgements areas-of-d-usage \
 	D1toD2 d-array-article d-floating-point deprecate dlangupb-scholarship dll-linux dmd \
 	dmd-freebsd dmd-linux dmd-osx dmd-windows documentation download dstyle \
 	exception-safe faq forum-template foundation gpg_keys glossary \
-	gsoc2011 gsoc2012 gsoc2012-template hijack howto-promote htod index \
+	gsoc2011 gsoc2012 gsoc2012-template hijack howto-promote htod index install \
 	intro-to-datetime lazy-evaluation menu migrate-to-shared mixin \
 	orgs-using-d overview pretod rationale rdmd regular-expression resources safed \
 	search template-comparison templates-revisited tuple \