search

sailfishos-chum / main

Documentation and issue tracker for the SailfishOS:Chum community repository
https://build.merproject.org/project/show/sailfishos:chum
MIT License
26 stars 4 forks source link

Overhaul README: Wording etc. #48

Closed Olf0 closed 2 years ago

Olf0 commented 2 years ago

@rinigus, if you have questions, suggestions, requests for adaptions etc., please let us discuss them first here. You as the principal maintainer of SailfishOS:Chum implicitly have the final say ("last word") on anything happening in this repo, but OTOH you know by now, that I set (almost) every character in a text deliberately. While switching off "maintainer commits" would be childish (and futile), I ask you not to use them without discussing first.

rinigus commented 2 years ago

Started reading it and would be happy to discuss. OK, this is then the first PR we have to handle, before #49 . Much of docs has been handled by @piggz, pinging him as well :)

piggz commented 2 years ago

One last change I would make ... add a link and description of adding the chum store meta data to the rpm .spec file

Olf0 commented 2 years ago

Thank you for revising the README. All in all, I think text has improved.

Good.

Almost all suggested changes are removal of forced HTML linkebreaks.

I see, though I tried to use them sparingly.

IMO they are less awkward than the strange tricks used before:

Furthermore, the looks are really awkward at some other places without forced line breaks:

In know well, that one should not try to force a HTML renderer into one's own ideas of formatting (because the easily backfires), and this is not what I want to achieve here. But your apparently strict policy of never using a \<br /> is hard to comprehend for me in above cases, especially when you suggest workarounds which definitely fall into the category "but that is not how it was intended to be used" (technically in the first two examples, semantically the other three). Can you please briefly denote, where your strong aversion of line-breaks originates.

At least I now understand why you repeatedly felt the urge to either eliminate the single line-breaks or convert them into a double line break when submitting my suggestions from issue #45.

BTW (& JFYI), I eliminated two forced line-breaks in PR #50: I avoid them when easily possible.

You are also using nbsp; in the text.

Which I hate to use, but IMO it is less evil than a line-break between "Sailfish" and "OS". I wish Jolla would have never altered the spelling from "SailfishOS" (before 2015) to "Sailfish OS". I usually ignore this change, but your "ambition is to become the principal software distribution for Sailfish OS". So I expected some appeasement to Jolla's spelling rules to be necessary.

Olf0 commented 2 years ago

One last change I would make ... add a link and description of adding the chum store meta data to the rpm .spec file

Done.

rinigus commented 2 years ago
  • The FAQ questions look really strange, if not solitary on a line, i.e., if the answer is directly appended to it. But an empty line breaks a list element into a list element and an independent line outside of the list.

Notice that this is a location where I haven't suggested to drop breaks.

  • URLs can span over a line end (at least I saw that in the preview): It makes them harder to see, click and comprehend that it is not two URLs, if they are not within a single line.

In practice, you just click at URL and focus on the next text rendered after clicking on it. I wouldn't worry about it - although it could have been easily my own hacky "workaround".

  • Sometimes it just makes sense to emphasise a sentence within a paragraph by letting it begin at the start of a line. Usually because it is important and shall not be quickly read over. Breaking the paragraph into two breaks the logical cohesion between the sentences, hence this is not a "solution", because it significantly alters the structure and meaning of a text.

Here I would oppose it. If it is within the paragraph then it should just be in there. If there is something important in the middle of the paragraph that you don't want to miss it then we have to either rewrite the paragraph and add that message in front or split the paragraphs into two. Having a linebreak within the paragraph, in my opinion, is not acceptable when we have a regular text. We can look through many texts from different backgrounds and it is rather common approach throughout.

So, please, if you wish to use a linebreak, unless we have such specific case as FAQ, then either decide whether it is new paragraph or skip it.

I guess the text above responds to your more general question regarding linebreaks.

Which I hate to use, but IMO it is less evil than a line-break between "Sailfish" and "OS".

I think this is OK as MarkDown is missing such feature as non-breakable-space, as we have in few other places. Just we will probably forget to add it and happily let it break there.

rinigus commented 2 years ago

Thank you very much for the changes! LGTM

Olf0 commented 2 years ago

@rinigus,

  • The FAQ questions look really strange, if not solitary on a line, i.e., if the answer is directly appended to it. But an empty line breaks a list element into a list element and an independent line outside of the list.

Notice that this is a location where I haven't suggested to drop breaks.

Well, https://github.com/sailfishos-chum/main/pull/48#discussion_r785462090. Thus they are gone now.

  • URLs can span over a line end (at least I saw that in the preview): It makes them harder to see, click and comprehend that it is not two URLs, if they are not within a single line.

In practice, you just click at URL and focus on the next text rendered after clicking on it. I wouldn't worry about it - although it could have been easily my own hacky "workaround".

See https://github.com/sailfishos-chum/main/blame/72f41cb65626ad16255d6a7d0863496ca7762036/README.md#L23. Later only the URL was adapted by flypig from build.merproject.org to build.sailfishos.org, until https://github.com/sailfishos-chum/main/pull/48#discussion_r785457642. But the "hacky workaround" and my forced line-break are gone now.

  • Sometimes it just makes sense to emphasise a sentence within a paragraph by letting it begin at the start of a line. Usually because it is important and shall not be quickly read over. Breaking the paragraph into two breaks the logical cohesion between the sentences, hence this is not a "solution", because it significantly alters the structure and meaning of a text.

Here I would oppose it. If it is within the paragraph then it should just be in there. If there is something important in the middle of the paragraph that you don't want to miss it then we have to either rewrite the paragraph and add that message in front or split the paragraphs into two. Having a linebreak within the paragraph, in my opinion, is not acceptable when we have a regular text. We can look through many texts from different backgrounds and it is rather common approach throughout.

To me this is a style question and there also are many texts handling this "my way", thus I am still surprised that you think of "Having a linebreak within the paragraph, in my opinion, is not acceptable when we have a regular text.", because "not acceptable" is a very strong rsp. strict stance. Anyway, we gained some mutual understanding, which is a good outcome from my POV.

Olf0 commented 2 years ago

Looking at the README as rendered at the sailfishos-chum/main frontpage now, made me wish to re-insert forced line-breaks at least at the locations where @rinigus indicated that they are acceptable for him. Thus, when I spotted a typo, I took the chance: PR #51

rinigus commented 2 years ago

@Olf0: agree about strong wording - should have used some lighter tone. Sorry about it.

Olf0 commented 2 years ago

@Olf0: agree about strong wording - should have used some lighter tone. Sorry about it.

Socially that was O.K. from my perspective, thus no need to say "sorry": You expressed your opinion WRT "forced line breaks" very clearly, but it never was directed "ad hominem". And I always prefer unambiguous statements over soft, ambiguous ones: "Clarity is paramount!"

Hence I do not think you "should have used some lighter tone", if that authentically was your opinion at that time. But I am very glad that you seem to have "lightened" the strength of your opinion a bit, because in my understanding your original stance left no room to apply "forced line breaks" at all, which conflicts with my belief that they are sometimes (although rarely) necessary.

Thus gaining some mutual understanding and seeing that PR #51 apparently was O.K. for you is a proper base for future contributions from my perspective. Thanks!

P.S.: Actually I have one file on my radar, which contains "forced line breaks" at places where even I do not think they are appropriate. A PR from me for fixing that might come some time. Edit: See PR #61.

rinigus commented 2 years ago

I am sure we can strike a balance, as we did with PR #51. Would just have to be sure that the break is, indeed, very needed there.