Fix Issue 17998 - Document Options for install.sh #1936

wilzbach · 2017-12-02T21:21:37Z

While this isn't perfect, it should provide a good basis for continuous improvements ;-)

I wasn't sure whether ~/dlang/install.sh or ./install.sh should be the recommended invocation.

dlang-bot · 2017-12-02T21:21:39Z

Thanks for your pull request, @wilzbach!

Bugzilla references

Auto-close	Bugzilla	Description
✓	17998	Document Options for install.sh

PetarKirov · 2017-12-03T10:05:03Z

Thanks, this was on my to do list as well ;)

PetarKirov

Thanks for pushing this forward!

PetarKirov · 2017-12-03T10:31:34Z

install.dd

+
+$(D_S $(TITLE),
+
+$(UL


I would like to start with a dense overview paragraph that gives reader an idea what this is all about.
What do you think about an introductory paragraph, along the lines of:

Introduction

The dlang.org/install.sh script is the official D version manager for DMD, GDC and LDC on FreeBSD, Linux and macOS.
Its features include:

Maintaining one or more portable compiler installations in the user's home directory (~/dlang/)

Maintaining the latest stable version of Dub (multiple dub version are not supported)

Self-updating via ~/dlang/install.sh update

Working without require administrative privileges

Minimal external dependencies (NOTE: I'm not sure if it makes sense to document commands used, besides curl, as this can easily go out of sync with the source, but still we should mention what the users needs to have on his system).

Supports 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.

Supports Fish shell, in addition to Bash-compatible shells.

For dmd, the installation of following versions is supported:

dmd - latest stable version

dmd-beta - latest beta version

dmd-nightly - the latest nightly release

dmd-<version> - specific official release (including beta releases)

dmd-branch - experimental compiler branches

For ldc, the installation of following versions is supported:

ldc - latest stable version

ldc-beta - latest beta version

ldc-<version> - specific official release (including beta releases)

For gdc, the installation of following versions is supported:

gdc - latest stable version

(Sorry for not writing directly in DDoc, but I am not the go.)

PetarKirov · 2017-12-03T11:46:03Z

install.dd

+$(H2 $(LNAME2 usage, Usage))
+
+$(CONSOLE
+./install.sh [&lt;command&gt;] [&lt;args&gt;]


Always use ~/dlang/install.sh. Avoid using relative paths, especially in documentation.

wilzbach · 2017-12-07T09:51:18Z

What do you think about an introductory paragraph, along the lines of:

I like it. I converted your text to Ddoc and made a few changes. Please feel free to improve upon them ;-)

andralex

see review

andralex · 2017-12-16T13:05:30Z

install.dd

+If you want, you can directly invoke it:
+
+$(CONSOLE
+curl https://dlang.org/install.sh | bash -s


I recall someone (@CyberShadow?) quoted a scathing article about this practice. Perhaps it would be best to not mention it.

AFAIK, it's fine if done right:
https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install

Well we do mention it on the downloads page too:

andralex · 2017-12-16T13:07:15Z

install.dd

+wget https://dlang.org/install.sh
+)
+
+If you want, you can directly invoke it:


Oh, also please avoid the use of "you" in documentation.

s/If you want, you can directly invoke it/Alternatively, the script can be invoked directly/

andralex · 2017-12-16T13:07:34Z

install.dd

+
+$(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:


s/your shell/the shell/

Use the recently introduced on hover info button on the downloads page to show a link to the install.sh script documentation.

wilzbach · 2017-12-18T05:59:24Z

Okay addressed the feedback.
I also switched to use the recently introduced "info on hover" button on the downloads page to link to the script documentation (instead of simply using "Explain").

PetarKirov · 2017-12-18T07:46:54Z

install.dd

+$(EXAMPLES
+~/dlang/install.sh uninstall dmd
+/install.sh uninstall dmd-2.071.1
+/install.sh uninstall ldc-1.1.0-beta2


Use ~/dlang/install.sh here too. It looks a bit confusing, otherwise.

PetarKirov · 2017-12-18T07:47:32Z

install.dd

+Run the respective `activate` script in a shell to use a compiler by default:
+
+$(CONSOLE
+source ~/dlang/&lt;installed-compiler&gt;/activate


You should also mention that for fish shell the command is:

source ~/dlang/<installed-compiler>/activate.fish

PetarKirov · 2017-12-18T07:49:01Z

install.dd

+~/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


Just for completeness (and easy copy-pasting) can you mention also:

~/dlang/install.sh install dmd-beta ~/dlang/install.sh install dmd-nightly

joakim-noah

My tweaks

joakim-noah · 2017-12-18T08:46:45Z

install.dd

+
+$(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.


Sentence is too long, break it with macOS. It provides.

joakim-noah · 2017-12-18T08:48:15Z

install.dd

+
+$(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`))


Introduce dub, don't assume they know it, the D package manager, dub.

joakim-noah · 2017-12-18T08:54:03Z

install.dd

+ $(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.)


Why is it "nested?" Can you activate a compiler inside another one's session?

Merge last sentence:

variables and a deactivate command, which reverts the variables to their old values.

Can you activate a compiler inside another one's session?

Yes it's a stack.

joakim-noah · 2017-12-18T08:56:15Z

install.dd

+curl https://dlang.org/install.sh | bash -s
+)
+
+$(P If no argument are provided, the latest DMD compiler will be installed.)


joakim-noah · 2017-12-18T08:57:43Z

install.dd

+
+$(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`.)


also make a copy of itself at

joakim-noah · 2017-12-18T09:00:26Z

install.dd

+            Installs the latest beta version of a compiler)
+        $(SWITCH $(SWNAME dmd-nightly),
+            Installs DMD nightly)
+        $(SWITCH $(SWNAME dmd-20170-02-10),


joakim-noah · 2017-12-18T09:02:26Z

install.dd

+~/dlang/install.sh install ldc-1.1.0-beta2
+)
+
+$(P Once a compiler can be activated for the current session:)


Why put this in its own paragraph? Merge it with the next sentence instead session, run the

wilzbach · 2017-12-18T09:41:11Z

@ZombineDev @joakim-noah thanks a lot for your feedback! Addressed.

wilzbach · 2017-12-18T09:44:21Z

install.dd

+$(H2 $(LNAME2 get, Downloading the installer))
+
+$(CONSOLE
+wget https://dlang.org/install.sh


How about:

mkdir -p ~/dlang && wget https://dlang.org/install.sh -O ~/dlang/install.sh

Yes, better to have a consistent install location, if the curl method installs it differently.

wilzbach · 2017-12-18T09:48:41Z

install.dd

+~/dlang/&lt;installed-ldc-compiler&gt;/ldc2
+)
+
+Users of the $(LINK2 https://fishshell.com, Fish shell), can `activate.fish`:


I put the note about the FISH shell at the end of this section as AFAICT it's not a very popular shell and it stops the reading flow awkwardly if put in-between.

No comma after shell),

joakim-noah

A few more tweaks

joakim-noah · 2017-12-18T10:46:55Z

install.dd

+ $(LI Maintaining one or more portable compiler installations in the user's home directory (`~/dlang`))
+ $(LI Maintaining the latest stable version of the D package manager, $(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, and a `deactivate` command, which reverts the modified variables to their old values.)


No comma needed after compiler, and variables,

You are absolutely right about the first occurrence, but isn't the second one the Oxford comma?
I reworded it slightly:

will setup the PATH, LIBRARY_PATH, .. PS1 environment variables, and a deactivate command

joakim-noah · 2017-12-18T10:47:43Z

install.dd

+ $(LI Maintaining the latest stable version of the D package manager, $(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, and a `deactivate` command, which reverts the modified variables to their old values.)
+ $(LI Supporting Fish shell, in addition to Bash-compatible shells.)


joakim-noah · 2017-12-18T10:54:08Z

install.dd

+$(H2 $(LNAME2 get, Downloading the installer))
+
+$(CONSOLE
+wget https://dlang.org/install.sh


Yes, better to have a consistent install location, if the curl method installs it differently.

joakim-noah · 2017-12-18T10:55:04Z

install.dd

+~/dlang/&lt;installed-ldc-compiler&gt;/ldc2
+)
+
+Users of the $(LINK2 https://fishshell.com, Fish shell), can `activate.fish`:


No comma after shell),

joakim-noah · 2017-12-18T10:56:43Z

install.dd

+)
+
+Alternatively, it is also possible to directly use a compiler by calling its
+binary directly.


Replace end with possible to call the compiler binary directly.

JinShil · 2017-12-19T00:10:51Z

This is really good, but we are introducing a maintenance burden and a fragile synchronization between this file and install.sh. Would it not be better to add this documentation to the --help output of install.sh and maybe generate this file as part of the build?

JinShil

Regardless, it's better to have it than not have it.

joakim-noah

No more tweaks, maybe linux shouldn't be capitalized, like macOS

wilzbach · 2017-12-19T03:09:35Z

but we are introducing a maintenance burden and a fragile synchronization between this file and install.sh. Would it not be better to add this documentation to the --help output of install.sh and maybe generate this file as part of the build?

Of course it would be better, but that's pretty difficult to do all the custom text, explanations and formatting.
I don't think that this file changes much (the installer has about 2-3 pull requests per month and they are mostly just upgrades to the release build system), so that it's worth looking into the effort of generating the page automatically.

OTOH the compiler help page changes quite a lot and we are incredibly bad in keeping it up to date. So if we want to invest time in generating something automatically, I think the dmd-*.html pages are a better candidate.

wilzbach · 2017-12-19T03:14:06Z

maybe linux shouldn't be capitalized

Hmm, I have only seen it written capitalized except for DMD's inconsistent version file.

(Also I am terribly sorry for forgetting to squash this. We really need to re-enable auto-merge-squash.)

MartinNowak · 2017-12-21T21:15:16Z

Would it not be better to add this documentation to the --help output of install.sh and maybe generate this file as part of the build?

Indeed figuring out how we can base those things on a common man-page like document would be helpful, but not that urgent as it's rarely changing.
https://github.com/fish-shell/fish-shell/blob/f563262cfda72aa291dcca4cd703b2ccba3331a9/share/tools/create_manpage_completions.py
What could be done fairly easily is dumping the outputs of ./install.sh --help, ./install.sh <cmd> --help verbatim into a code block, but it's less versatile than the docs in this PR.

dlang-bot added the Enhancement label Dec 2, 2017

wilzbach mentioned this pull request Dec 2, 2017

Update README.md ldc-developers/ldc#2421

Merged

PetarKirov reviewed Dec 3, 2017

View reviewed changes

wilzbach force-pushed the fix-17998 branch from 79a5aea to d9e4ebf Compare December 15, 2017 20:36

wilzbach requested review from andralex, CyberShadow and MartinNowak as code owners December 15, 2017 20:36

wilzbach force-pushed the fix-17998 branch from d9e4ebf to 8e0103c Compare December 15, 2017 20:37

andralex approved these changes Dec 16, 2017

View reviewed changes

andralex reviewed Dec 16, 2017

View reviewed changes

wilzbach force-pushed the fix-17998 branch from 8e0103c to a714431 Compare December 18, 2017 05:48

wilzbach added 3 commits December 18, 2017 06:53

Fix Issue 17998 - Document Options for install.sh

cddf449

Remove usage of you/your

294ea98

Show an info button to the script on hover

382c4b5

Use the recently introduced on hover info button on the downloads page to show a link to the install.sh script documentation.

wilzbach force-pushed the fix-17998 branch from a714431 to 382c4b5 Compare December 18, 2017 05:55

PetarKirov reviewed Dec 18, 2017

View reviewed changes

joakim-noah suggested changes Dec 18, 2017

View reviewed changes

wilzbach added 2 commits December 18, 2017 10:31

Address ZombineDev's review

22ddffd

Address Joakim's review

5940bf0

More tweaks

6bc6f37

wilzbach commented Dec 18, 2017

View reviewed changes

Mention activate.fish

9904471

wilzbach commented Dec 18, 2017

View reviewed changes

joakim-noah suggested changes Dec 18, 2017

View reviewed changes

wilzbach added 3 commits December 18, 2017 22:44

Install wget output to ~/dlang/install.sh

4c5a048

Address Joakim's review

c817d2b

Minor tweaks.

594234e

JinShil approved these changes Dec 19, 2017

View reviewed changes

joakim-noah approved these changes Dec 19, 2017

View reviewed changes

wilzbach added the auto-merge label Dec 19, 2017

dlang-bot merged commit 04bf20e into dlang:master Dec 19, 2017

wilzbach deleted the fix-17998 branch December 19, 2017 03:10

wilzbach mentioned this pull request Jan 31, 2018

Always display the download icon #2154

Merged


		$(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:


		$(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.


		$(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`.)


		$(D_S $(TITLE),

		$(UL

Fix Issue 17998 - Document Options for install.sh #1936

Fix Issue 17998 - Document Options for install.sh #1936

Conversation

wilzbach commented Dec 2, 2017

dlang-bot commented Dec 2, 2017

Bugzilla references

PetarKirov commented Dec 3, 2017

PetarKirov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Introduction

Choose a reason for hiding this comment

wilzbach commented Dec 7, 2017

andralex left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wilzbach commented Dec 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joakim-noah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wilzbach commented Dec 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joakim-noah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JinShil commented Dec 19, 2017 • edited Loading

JinShil left a comment

Choose a reason for hiding this comment

joakim-noah left a comment

Choose a reason for hiding this comment

wilzbach commented Dec 19, 2017

wilzbach commented Dec 19, 2017

MartinNowak commented Dec 21, 2017

JinShil commented Dec 19, 2017 •

edited

Loading