Create binary.md documentation #28822

miccal · 2017-01-10T09:45:33Z

vitorgalvao · 2017-01-10T15:31:41Z

doc/cask_language_reference/stanzas/binary.md

@@ -0,0 +1,48 @@
+# binary
+
+In the simple case of a string argument to `binary`, the source file is linked into the `/usr/local/bin` folder on installation. For example (from [operadriver.rb](https://github.com/caskroom/homebrew-cask/blob/60531a2812005dd5f17dc92f3ce7419af3c5d019/Casks/operadriver.rb#L11)):


I think we usually call them “directories” not “folders”. Or maybe we’re inconsistent on that. I prefer the former.

vitorgalvao · 2017-01-10T15:37:03Z

doc/cask_language_reference/stanzas/binary.md

+creates a symlink to:
+
+```bash
+/usr/local/bin/operadriver


This isn’t strictly true. In practice we use $(brew --prefix)/bin. Most of the time that will translate to /user/local/bin, but not always. See #21372.

Fixing it in https://github.com/caskroom/homebrew-cask/blob/master/doc/cask_language_reference/all_stanzas.md (#28837).

vitorgalvao · 2017-01-10T15:37:48Z

doc/cask_language_reference/stanzas/binary.md

+/usr/local/bin/operadriver
+```
+
+from a source file such as:


I don’t think this section is necessary. It’s not that useful to know where it’s linked from, that’s a more advanced detail.

I followed the same language as used in app.md which says the same thing.

Happy to remove it, though.

I think we can remove it from app.md as well. As long as it’s consistent, I’ll leave it to what you find is clearer.

I think that it is better in the binary because it actually is a symlink, and users would like to know where the symlink points to.

It can be removed from app.md though, I think.

I think that it is better in the binary because it actually is a symlink, and users would like to know where the symlink points to.

It can be removed from app.md though, I think.

Agreed.

vitorgalvao · 2017-01-10T15:39:32Z

doc/cask_language_reference/stanzas/binary.md

+
+## Renaming the Target
+
+You can rename the target which appears in your `/usr/local/bin` directory by adding a `target:` key to `binary`, for example to be to be consistent with other command-line tools like [changing case](https://github.com/caskroom/homebrew-cask/blob/070a3bdeadf339892268d79aded9108ba7960f32/Casks/praat.rb#L12):


We can name it “binaries directory” or something, here, instead of /usr/local/bin, since as previously noted, it might not be that location.

The examples could be taken directly from https://github.com/caskroom/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/app.md#target-should-only-be-used-in-select-cases, for consistency.

We can name it “binaries directory” or something, here, instead of /usr/local/bin, since as previously noted, it might not be that location.

Fixed.

The examples could be taken directly from https://github.com/caskroom/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/app.md#target-should-only-be-used-in-select-cases, for consistency.

That is where I got them from.

vitorgalvao · 2017-01-10T15:42:25Z

doc/cask_language_reference/stanzas/binary.md

+binary 'minishift-darwin-amd64', target: 'minishift'
+```
+
+## target: May Contain an Absolute Path


While useful, this part is referring to artifact, not binary. We don’t want to encourage absolute paths in binary, target:. The section should be removed or made clearer that it is referring to artifact as a companion to binary.

Again, I followed the same language as used in app.md which says the same thing.

Happy to remove it, though.

Although the example is nice, as it is a binary example.

Might actually make more sense to remove this from app.md also and leave it in binary.md.

Lets do one better. I think that I was the one to originally write these, and that I put target in app.md for lack of a better place. We could either:

Split the documentation of target: to a new document and link there from both app.md and binary.md

Remove all target: documentation from binary.md and link to the section in app.md.

I’m partial to the second one (seems to be as clear, and requires less files.

Sounds good to me. Please add the third example, though, about cleaning up the name.

I'm offline for a while - please fell free to edit the file.

I’m instead removing mentions of binary.

In this document, we can say that for target:, the app.md document should be followed, but that the select cases don’t apply as rigidly and it’s fine to take some extra liberties with target: to be consistent with other command-line tools, like changing case, removing an extension, or cleaning up the name.

This way it’ll be more consistent with what we do with the other repos (we tell users to check the rules in this one, and point out the differences there).

miccal · 2017-01-11T01:48:56Z

Thanks for all the help @vitorgalvao.

vitorgalvao · 2017-01-11T02:59:57Z

@miccal Thank you for starting it in the first place.

Create binary.md

e4eb129

Closes #25423.

miccal added awaiting maintainer feedback Issue needs response from a maintainer. documentation Issue regarding documentation. labels Jan 10, 2017

miccal changed the title ~~Create binary.md~~ Create binary.md documentation Jan 10, 2017

miccal added 4 commits January 10, 2017 21:55

Update binary.md

fe7b78b

Update binary.md

09857f0

Update binary.md

3ab806b

Update binary.md

9fb4538

vitorgalvao suggested changes Jan 10, 2017

View reviewed changes

vitorgalvao mentioned this pull request Jan 10, 2017

all_stanzas.md: be more precise in binary installation dir #28837

Merged

miccal and others added 4 commits January 10, 2017 23:56

Update binary.md

f9ee909

Update binary.md

9e56592

Update binary.md

b23809a

Update binary.md

4c1f36e

vitorgalvao approved these changes Jan 10, 2017

View reviewed changes

miccal removed awaiting maintainer feedback Issue needs response from a maintainer. documentation Issue regarding documentation. labels Jan 10, 2017

miccal merged commit 334f331 into master Jan 10, 2017

miccal deleted the miccal-binary-doc branch January 10, 2017 23:53

Homebrew locked and limited conversation to collaborators May 9, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create binary.md documentation #28822

Create binary.md documentation #28822

miccal commented Jan 10, 2017

vitorgalvao Jan 10, 2017

miccal Jan 10, 2017

vitorgalvao Jan 10, 2017 •

edited

Loading

miccal Jan 10, 2017

vitorgalvao Jan 10, 2017

miccal Jan 10, 2017

vitorgalvao Jan 10, 2017

miccal Jan 10, 2017 •

edited

Loading

vitorgalvao Jan 10, 2017

vitorgalvao Jan 10, 2017

vitorgalvao Jan 10, 2017

miccal Jan 10, 2017

vitorgalvao Jan 10, 2017

miccal Jan 10, 2017 •

edited

Loading

vitorgalvao Jan 10, 2017

miccal Jan 10, 2017 •

edited

Loading

miccal Jan 10, 2017

vitorgalvao Jan 10, 2017 •

edited

Loading

miccal Jan 10, 2017

miccal commented Jan 11, 2017

vitorgalvao commented Jan 11, 2017

		@@ -0,0 +1,48 @@
		# binary

		In the simple case of a string argument to `binary`, the source file is linked into the `/usr/local/bin` folder on installation. For example (from [operadriver.rb](https://github.com/caskroom/homebrew-cask/blob/60531a2812005dd5f17dc92f3ce7419af3c5d019/Casks/operadriver.rb#L11)):


		## Renaming the Target

		You can rename the target which appears in your `/usr/local/bin` directory by adding a `target:` key to `binary`, for example to be to be consistent with other command-line tools like [changing case](https://github.com/caskroom/homebrew-cask/blob/070a3bdeadf339892268d79aded9108ba7960f32/Casks/praat.rb#L12):

Create binary.md documentation #28822

Create binary.md documentation #28822

Conversation

miccal commented Jan 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vitorgalvao Jan 10, 2017 • edited Loading

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

miccal Jan 10, 2017 • edited Loading

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

miccal Jan 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miccal Jan 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vitorgalvao Jan 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miccal commented Jan 11, 2017

vitorgalvao commented Jan 11, 2017

vitorgalvao Jan 10, 2017 •

edited

Loading

miccal Jan 10, 2017 •

edited

Loading

miccal Jan 10, 2017 •

edited

Loading

miccal Jan 10, 2017 •

edited

Loading

vitorgalvao Jan 10, 2017 •

edited

Loading