search

Homebrew / legacy-homebrew

💀 The former home of Homebrew/homebrew (deprecated)
https://brew.sh
26.97k stars 11.34k forks source link

Clarify and ease the ReadMe.md - issue #50663 #50664

Closed JMoVS closed 8 years ago

JMoVS commented 8 years ago

Improve human parseability

referring to issue #50663

JMoVS commented 8 years ago

any additional work required by me to get this merged?

ilovezfs commented 8 years ago

I find the current version more clear than this, so :-1:

JMoVS commented 8 years ago

Well, then please for the future get your preliminary consesus among the homebrew-maintainers more worked out as I think the response was universally positive in https://github.com/Homebrew/legacy-homebrew/issues/50663 and I was encouraged to do it and it's frankly a little bit frustrating to first be encouraged to open a PR for this, and then said that it's not gonna make it when the PR is exactly like I was supposed to do it.

hanxue commented 8 years ago

I think the new text is clearer. When I first looked at the original text, I got mixed up between brew and homebrew-core

ilovezfs commented 8 years ago

old unboldlink/unboldlink: unboldtext (unboldtext [code]) unboldtext unboldlink/unboldlink: unboldtext (unboldtext [code]) unboldtext

new boldtext/boldtext: unboldlink/boldlink (unboldtext [code]) unboldtext boldtext: unboldlink/unboldlink

old link1: X without A (i.e., without the former a) link2: A (i.e., the former a) for X

new A: link1 (former a) X: link2

UniqMartin commented 8 years ago

Just for comparison, here's what the old version looks like and what the new version would look like.

Old:

New:

I still agree that the latter is easier to parse and is an improvement. However, I don't understand why the “brew” in “Homebrew/brew” is not highlighted while “homebrew-core” in “Homebrew/homebrew-core” is. Personally, I'd find it even easier to read if all the highlighting was omitted, i.e. there were just two list items of plain text (except for the styling due to hyperlinking).

[…] and it's frankly a little bit frustrating to first be encouraged to open a PR for this, and then said that it's not gonna make it when the PR is exactly like I was supposed to do it.

I feel your pain, but not every issue is discussed among all maintainers to find a common opinion. If we did this, we would hardly get any work done. Hence some maintainers chime in later with a diverging opinion—or not at all. And quite frankly, it's not like you wasted hours of your time preparing this PR and it wasn't even rejected yet. Whether or not this will be merged, we still appreciate your contribution!

MikeMcQuaid commented 8 years ago

I personally agree with @UniqMartin's comments but prefer the original version. I don't have strong feelings either way though.

JMoVS commented 8 years ago

We all have emotions, so please forgive me, @UniqMartin ;-)

I personally wanted to introduce the bold parts because for my vision, these help tremendously in human parsing. What do you guys think of:

It's I think more conistent in the formatting and it also now nicely aligns.

UniqMartin commented 8 years ago

@JMoVS I'm happy with what you suggested, so please update your PR accordingly! I think it is an improvement. And even if some people feel it's not, I'm confident that it's not making things worse.

Let's get this out, so people know (better) where to go to, and then let's move on with reaping the benefits of our beautifully split repositories. :smiley_cat:

JMoVS commented 8 years ago

Do you guys need it rebased and squashed to one commit? I ask because up to this point, I only used the GitHub webpage UI for this and I don't think there is a way to rebase in it. ¯(ツ)/¯ (I can of course pull to my local computer, rebase and force-push up ;-) )

MikeMcQuaid commented 8 years ago

I'd still prefer to avoid the bolding but otherwise am happy.

UniqMartin commented 8 years ago

Do you guys need it rebased and squashed to one commit?

That's not necessary. We will squash them when merging your changes.

I'd still prefer to avoid the bolding but otherwise am happy.

How strongly do you feel about the bolding? Strong enough not to merge as-is?

JMoVS commented 8 years ago

About the bolding, @mikemcquaid , for me as I see it currently there are 2 places that are bolded that are alike. 1. is the formula.../package manag..., 2nd is the URL. I personally would still like but don't feel super strong about the URL part. WHat really does help me for my visual cortex is the bolding at the beginning of "formulae/packages" and "package manager". Eg:

MikeMcQuaid commented 8 years ago

I'd just rather we didn't have the bolding, feels weird to me. If any other maintainers disagreed strongly I think they'd have chimed in so let's just remove it and I'll merge. Thanks!

JMoVS commented 8 years ago

@mikemcquaid I don't currently get what is now a consensus. I will refrain from arguing with you as per homebrew code of conduct ;-), I'll just take it that you don't seem to be convinced by my arguing for bolding in the beginning area (long story short: for me it helps so that I don't have to read the whole two lines, the two bold texts are then enough).

If you tell me exactly what should be changed, then I can do that. for me it wasn't clear whether you meant all bolding or specific parts as I layed them out earlier

MikeMcQuaid commented 8 years ago

@JMoVS Please remove all bolding.

UniqMartin commented 8 years ago

Alright, this hasn't seen any updates in two weeks. It's apparently not going anywhere and frankly it's not really a very pressing issue, thus I'm closing this.

JMoVS commented 8 years ago

I totally forgot about this. I have removed the bolding but it doesn't seem to update this PR now. Should I opne a new one or do something different?

UniqMartin commented 8 years ago

I have removed the bolding but it doesn't seem to update this PR now. Should I opne a new one or do something different?

That's because the PR was closed. I reopened it and merged your changes now. Thank you for this contribution to Homebrew, @JMoVS! :tada: