When you give a basic touch of modern design to a README and critize their replies they end the conversation with

'locked and limited conversation to collaborators'

'We appreciate the effort'

Sure doesn't look like it.

'X is highly specialized software'

Like most other software? And?

'The docs are fairly out of date, and need a complete rewrite, not this kind of graphical adjustment, so it would do more harm than good to present information of how to run this application in a secondary page along with random outdated info.'

So you are too lazy to update them, probably won't for a long time and have a problem with updating the outdated information's design despite that not actually changing the situation.

Disregarding the fact that the 'graphical adjustment' work even if you update the content.

Got it, right.

Lol, now I hear 'Never should have come here' in my head.

@ElectroArchiver out of curiosity: GitHub / open accessible repo?

Always good to know whom to put on the naughty list.

Some repositories / repository managers need a new personality, that's for sure.

@IntrusionCM Don't think it will be relevant to you but it's danbooru. ( Image board platform )

@ElectroArchiver Your graphical adjustments usually involve cluttering markdown with HTML which makes tedious and long-overdue content updates even more tedious and less likely to get done. I would only ever incorporate your design ideas in a project in the shape of a script that renders the human-readable README.md into a pretty README.html (or possibly a single README.mdx since React components at least separate the semantic component tree from the HTML).

I haven't seen this particular PR, I'm mainly going off the parts of your work I've seen in the past.

@lbfalvy Pretending again that Markdown isn't an extension to HTML?

Oh no, I'm using <div align = center> for centering how criminal, also those dreaded <br> tags that I'm using instead of \ like a good C programmer, oh right they are evil and I should let the browser do the line adjustment.. Oh wait no browser actually does it, besides mobile, but not because they do it on purpose but because they have a small screen size, though that is missing the point since they aren't the fucking audience of a software repo to begin with.

@ElectroArchiver Markdown isn't an extension of HTML. Github markdown is an extension of markdown that supports a subset of HTML's features. Markdown is a limited set of simple plaintext formatting rules that are designed to help converters - such as Github's markdown parser - recognize the inherent structure. Among the primary targets of a markdown document is a text editor.

README.md in particular can be treated as a file mainly designed for viewing through a particular set of formatters, in which case it may make sense to disregard the readability of the plaintext and use HTML, but in that case in my opinion it should be treated as a binary and not a source file, and better, human-readable languages (such as Markdown) should be used as its source. Also at that point it's less ambiguous if you use the .html extension such that clients that can't parse your file don't display the source.

@lbfalvy

You write:

Your graphical adjustments usually involve cluttering markdown with HTML which makes tedious and long-overdue content updates even more tedious and less likely to get done.

But then recommend using pure html files?

Who in their right mind would like to write html files when they just want markdown with a bit of formatting, which is entirely possible as can be seen.

Btw, you should correct your multiple repositories LICENSE.md files, I'm afraid they aren't markdown ..

@ElectroArchiver I suggested either fully sticking to human-friendly Markdown or adopting HTML along with a way to generate it. My point in essence is that information should not be edited by humans in HTML format because we have better tools.

@lbfalvy Sorry, I live on the gradient, not in black & white.

Btw, is the reason you're afraid of <br> tags the same that makes you not want to add newlines to your code?

https://github.com/lbfalvy/...

Very impressive how you mitigated using any ; in all of that cramped code, are you sure you didn't want to write Python instead?

@ElectroArchiver That's actually not my most compact file, try react-await.

Thanks for highlighting the issue though. To anyone who knows enough about distributed systems and locking to have business with that file the code should be perfectly meaningful, however, it could definitely do with some comments.

@ElectroArchiver I don't live in black and white, I just think that there's no point on the spectrum where writing content in HTML makes sense. If simplicity is the main goal markdown should be preferred, if aesthetics are important a preprocessor should be involved. I think that HTML isn't a maintainable format, and the only reason to edit large bodies of HTML is to maintain old systems that can't be migrated to a better solution.

@lbfalvy SPACE, I need space!

@killermenpl

'the buttons don't even look good on mobile...'

Ah yes, because mobile is a relevant target audience for an image board project README.

Also, oh no, I used content separation, a basic strategy to not drown the user with all the available information and allow them to choose what they came for.

Guess we should abolish menus, searches, folders, .. as well

While you're digging through my repos, my blog is built on MDX which enables me to write content in markdown and format it with the precision of a modular preprocessor chain, and also to embed isolated snippets of HTML without ever mixing content and code. I think you'll like the solution, though maybe it's a bit overengineered for readmes. The preprocessor also exists as a self-contained package.

The blog's code:
https://github.com/lbfalvy/...

@ElectroArchiver I don't think space helps here. It's useful if it separates things that need to be considered separately, but all parts of the mutex are a single unit and need to be considered in the context of all the others.

@lbfalvy Yes, good for actual pages, not for README's ( if they don't contain continually regenerated content or something )

@lbfalvy Let me fork it real quick and try something~

@ElectroArchiver If it's html, it's a page. If it's not a page, it shouldn't contain html. If the core concept of the non-html formatting language is to look similar to the output, it should _especially_ not contain html.

@killermenpl

'And you know what looks perfectly fine on mobile? Plain Markdown.'

Yes and no, having to scroll two miles because everything is in the README is not perfectly fine.

'You sliced it into pieces and separated them by force.'

Right, because those pieces were already separate sections marked with H2 headers.

'And I think in this discussion I'm gonna side with the guy that actually writes code, rather than having 300 useless forks...'

Useless forks, wow genius, forks from when I commited, tryed something out or think about trying something out have some sort of relevance to you?

Who cares about someones repository count?

Also if you actually cared about what I do, you would have looked for the tools I have written, which you clearly didn't.

https://github.com/franksouza183/...

@killermenpl Oh you are quite the comedian.

Not sure if you got it, but on my ElectronicsArchiver account I mainly do documentation related stuff, I merely pointed you to one of my code contributions since you were asking so nicely for it.

What I choose to show off on my profile is at my sole discretion and since I don't mainly write tools on it, I chose not to.

Btw, maybe you should, for yourself, link a valid GitHub profile, I was interested to see what a person such as yourself would have to present, but at last there wasn't even anything for me to check out, what a shame!

@lbfalvy Btw, thanks for writing tests <3 ( for your react-await repo )

Now if Jest just didn't spam my console with pages upon pages of error for one simple thing, that would be great, lol.

@killermenpl No reason for getting personal, maintaining documentation is a useful contribution.

@ElectroArchiver I think it can be disabled, there's lots of asynchronity and the exact order of operations matters. Not sure when I started adding log toggles to my tests so maybe this project is older than that.

@ElectroArchiver anyway the most important part is the summary at the bottom, you can run it in a separate window or a tmux pane that's just a couple lines tall.

@killermenpl Thanks.

Well some of it I can't really read, not sure what language that is?

Multiple don't have READMEs, mhm.

But I commend you for your

'Bloat that will not be implemented'

section 👍

@lbfalvy Tried my hand at your code, ofc still passes all 15 test.

https://github.com/ElectronicsArchi...

And god fuck

export type WithPromisesAndObtainers<T> = {

[ P in string & keyof T ] : ( k : SelfPromiseOrObtainer<T,P> ) => void

} [ string & keyof T ] extends {

[ P in string & keyof T ] : ( k : infer I ) => void

} [ string & keyof T ] ? I : never

a great reason to despise typed language~

@ElectroArchiver Javascript isn't typed so I had to assume that anything can change into anything on any render. In a sensible typed language I would've made the following (compile-time enforced) assumptions:

1. the set of props can never change

2. the type of props can never change, nor whether they're provided as promises or immediate values

3. the order of props can never change

And of course all of these are fixed at compile-time and can be used with clever generics to write like four functions for the four cases and generate the rest with like four lines of type-level metaprogramming.

Because this is javascript, absolutely everything can change, and Typescript decided to introduce a declarative programming language for types rather than specifying which JS patterns are allowed and which aren't because they're massive footguns anyway. I'm just tagging along by writing JS that checks types at runtime and describing what it does using TS.

@ElectroArchiver You use so many blank lines that they lose significance and don't help readability, I recommend you increase the line height of your IDE and start using blank lines as a signal rather than to make it less cramped. The files are so long I forgot what some variables contained by the time I got to the end (which was already the case) but now I had to scroll back a full screen to find out (this was your addition to the problem).

Anyway it's an overall improvement so if you make a PR I'll merge it.

@ElectroArchiver Thanks a lot, you improved the code massively, pretty much everything apart from the

/\n/\n\n/g

is objectively much better than it was.

@lbfalvy Well if files get too long in my style, I know that they should be split up~

@lbfalvy

'Anyway it's an overall improvement so if you make a PR I'll merge it.'

Just did it to try my hand at it, but if you like it, sure~

@ElectroArchiver I'm not sure what more could be split up apart from Await itself, the rest pretty much have atomic well-defined responsibilities. Beyond a certain point splitting files also starts to hurt readability because you have more very similar files to check before you'd find the instruction you were looking for. I didn't want to split up Await because at the time I intended on extracting the ref forwarding logic into a separate package for other HOCs.

@lbfalvy Made it a draft so you can note anything you want to have changed before merging.

https://github.com/lbfalvy/...

@lbfalvy Well type definition and the isObtainerPair function could be placed in it's own thing

Wow, I initially thought you just did it in one function but apparently I wasn't exaggerating, literally every statement is separated by a blank line from the preceding and following statements.