Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Notebook Is A Better Readme

matyunya-readme.ellx.app

Post reply on HN
Print view View original

51–60 of 79 posts

Re: Notebook Is A Better Readme

#51

Post by gkya »

ldiracdelta wrote: post #23
qayxc wrote: post #11

Earlier quoted context omitted.

Markdown is still just plain text without any "crazyness". Stuff like "## Header" isn't any more "crazy" than the ASCII art used in many Readme's of old and on top of that doesn't rely on specific monospace fonts or fixed width. And more advanced stuff like hyperlinks or tables are hard to do "right" in text anyway, since it's basically meta data without an objective "right" or "wrong" way of representing it. I also…

I have a 4k 43" monitor. Now I can easily see 8 separate chunks of code with my monitor split into 4 columns and 2 rows. Or I can see 2 columns and have the app on the left half of the screen with a debugger. I break the 80-char rule frequently, but having code be limited in width is still useful.

I find soft-wrapping code pretty tedious, so even with huge screens IMHO indeed breaking around 80-100 (accounting also for indentation) is nice.

BTW I recently go a 24" screen (I was all about laptops, turns out I was torturing myself...) and I can easily fit 3 columns in Emacs, with a large-ish point size (238 chars across the monitor, DejaVu Sans Mono). If it's not a preference thing, and assuming (corrected-to-)fine eyesight, shouldn't 43" be capable of like 8x2 easily?

Re: Notebook Is A Better Readme

#52

Post by znpy »

adkadskhj wrote: post #50
znpy wrote: post #5

Oh god please no. The last thing we need is more dependance on web browsers.

Web browsers are an operating system these days. Having more dependence on them is like having more dependence on Linux/Windows/OSX. It's a pipedream to think they will remain consistent and/or shrink in use case. Like it or not, this is here to stay. What we should fight against, imo, is not browsers as an idea - but the lack of diversity. We're in a reality where we all but only two/three browsers - it would be as…

> Like it or not, this is here to stay

Like it or not, the web browser game is one monopoly after another. First it was internet explorer, now it's chrome.

It's been happening again and again, the only way not to lose is not to play the game.

Thus, relying less on the browser is a good thing.

Re: Notebook Is A Better Readme

#53

Post by pietrovismara »

ktpsns wrote: post #15
prepend wrote: post #7

No, I don’t think so. Readme pages should be the lowest common denominator to information on the project no matter where you come across it. I think markdown is probably as fancy as it can get and still be readable in the terminal after I clone the repo, or any ide, or the browser. I think of it as a more formatted man page. Would I want a man page to be interactive? Or only work in a browser. I also think if GitHub…

This. Readme files should be readable by anyone. That's one of the promises in the filename (it is readable ;) ). There is a reason readme files are not PDF files.

Ok but then you get README files that are useless on their own, containing basically only a brief descriptions and several links to github pages / docs website. What good does it make to be able to read that on your terminal?

Re: Notebook Is A Better Readme

#54

Post by sgillen »

enriquto wrote: post #37
globuous wrote: post #30

Org mode is a better readme and a better notebook :)

Is there a way to enjoy all the pleasures of org mode without having emacs installed on my computer? If there isn't, it seems that "org mode" is a very bad name and it should be called simply "emacs". Or, if you want to be too precise, "emacs, with some configuration tweaks".

You can certainly enjoy org mode documents read only without emacs, it’s ultimately plain text.

If you want to edit org files I really don’t think there is a good substitute for emacs if you want all the features, however you can definitely do basic modifications with any text editor.

Re: Notebook Is A Better Readme

#55

Post by enriquto »

gkya wrote: post #49
enriquto wrote: post #37

Earlier quoted context omitted.

Is there a way to enjoy all the pleasures of org mode without having emacs installed on my computer? If there isn't, it seems that "org mode" is a very bad name and it should be called simply "emacs". Or, if you want to be too precise, "emacs, with some configuration tweaks".

It's for organisation of information and it's an Emacs "mode". It's as much "emacs with some configuration tweaks" as VS Code is "chromium, with slightly improved ". W.r.t. the good question in a comment that definitely has more than just that, yes, there are partial ports of Org mode to vim, VS Cod{e,ium}, and AFAIK Sublime Text, but Org does make use of some facilities of Emacs that are not as easy to replicate on…

> VS Code is "chromium, with slightly improved "

Ha! I love this, definitely going to say it in public.

Apart from this joke, I asked a well-intentioned question. I have seen people doing magic with org-mode, treating text documents as if they were notebooks, running snippets of code by selecting them, then having the output as text. I would like to do something similar in vim, if possible.

Re: Notebook Is A Better Readme

#56

Post by dummy_physicist »

I prefer my readmes in plain text formats, be it Markdown, AsciiDoc, or unstructured txt. This reminds me of two interesting projects, maid[0], a task runner that uses markdown files, and mandown[1], a markdown pager that improves reading markdown files in the terminal.

[0]: https://github.com/egoist/maid

[1]: https://github.com/Titor8115/mandown

Re: Notebook Is A Better Readme

#57

Post by Chris2048 »

znpy wrote: post #52
adkadskhj wrote: post #50

Earlier quoted context omitted.

Web browsers are an operating system these days. Having more dependence on them is like having more dependence on Linux/Windows/OSX. It's a pipedream to think they will remain consistent and/or shrink in use case. Like it or not, this is here to stay. What we should fight against, imo, is not browsers as an idea - but the lack of diversity. We're in a reality where we all but only two/three browsers - it would be as…

> Like it or not, this is here to stay Like it or not, the web browser game is one monopoly after another. First it was internet explorer, now it's chrome. It's been happening again and again, the only way not to lose is not to play the game. Thus, relying less on the browser is a good thing.

So, will you forsake all propriety computer architectures too? And wireless tech?

Re: Notebook Is A Better Readme

#59

Post by IfOnlyYouKnew »

It seems like the framing around Readme sort-of backfired. It doesn't strike me as the core of this project, which is really a different take on the colab/jubyter paradigm.

I like the idea of spreadsheets as a first-class citizen in such a concept.

Re: Notebook Is A Better Readme

#60

Post by vadansky »

I think it's funny that since I had js disabled all I saw was "Error - blah blah blah" and I thought this was arguing AGAINST using a notebook as a readme.

Looking at umatrix all the js is coming from a CDN too. I think it show the obvious benefit of readmes compared to a notebook which might be useless in 10 years due to link rot or the CDN going under.

Post reply on HN