FWIW, from what i remember facebook's redesigns were never just a visual thing. they always added and pushed some functionality, made some things much harder to find, or quietly removed things entirely.
A similar thing happened when Last.fm did their huge redesign. The new website was all js now, and they quit all support on the forums, messaging, pretty much all the old ways of communication between users. And for me, that was awful, since i was a part of a music collective that communicated primarily on those forums. After that everybody dispersed.
So outrage at a redesign is not always unfounded or silly. Web companies tend to hide things in them.
For literary fiction, literary friends and book reviews. Also, anytime you see a name come up again and again, look into getting a something they have written. I bought Dostoyevsky because I kept seeing him come up (worth it).
Find small/independent presses that do cool things; even independent presses as large as New Directions will have a certain culture you can base opinions off of and figure out if its worth your time. Note that if its an imprint of one of the Big 5 theres no way to know if the book is gonna be worth it based on that.
And read books in translation. By virtue of being translated you already know its worth somebody's time, bad books arent often translated. And often they are hella good.
I loved thethecouple of books by dostoyevsky i have read. They were difficult to get into, but it occurs to me one of the really interesting and pleasant things about reading is attuning yourself to a writers tempo, patterns and word play. It forces you to adjust your own internal voice.
Pretty sure most folk in Hamlet get a bad deal in the end, and Hamlet's brooding and whining doesnt outweigh that. Ophelia literally goes mad and is driven to arguable suicide. Everyone that mattered dies, and if that is outweighed by Fortinbras and his good fortune in the end. Hamlet is Icarus if anything, since it only goes well for him for a moment while everybody else is on a downward spiral.
Think of it this way; the last time you cooked this dish there was way too much and youd prefer not to do that again. This would help.with that problem.
I guess it also makes more sense for baking than cooking.
But that's not what this scenario presents. OP was specifically talking about not wanting to leave ingredients around. He's solving a different problem.
All ingredients move together in ratios (got that, totally understand) so I understand HOW this work. What I was commenting on was WHY someone would cook this way. Again, I'm not saying it's wrong, it's just a problem I've never encountered. If I only used 150G of butter and had 100G left, then I have 100G of butter for whatever else I'm cooking.
I'm sure scenarios can be presented for why this is a problem that needs solving (storage space, product expiring, etc) it's never been a way I personally did things.
Perhaps I missed it, but i didn't see anything about physical copies, i.e. it seems this is focused (exclusively?) for the ditigal reader. Is that the case?
> I would skip man pages are they just aren’t used that often anymore.
I understand that man pages might represent a minority, but I cannot express enough how wonderful it is to get the full manual of a program without interfacing with the web. Not to mention how powerful that is, since most apps have short names that are difficult to search for, but how accessible that makes the application.
For people that like man pages (there appears to be lots of you) do you think that man pages are more important than web or in-cli docs? Or just that they should be written in addition to and not missed out on?
My (current) position is that they're useful, but not worth the extra effort for most CLIs. It's a cost-benefit thing.
I'm genuinely curious as I've never had anyone request man pages in our CLI.
> do you think that man pages are more important than web or in-cli docs?
Yes.
* Web docs are a problem because I don't always have access to the internet when trying to do something on my computer, and usually there are so many kinds of web doc generators that you have to figure out how the information you want is laid out. Web docs are useful as a quick-start guide or a very lengthy reference guide -- but not for the common usecase of "is there a flag to do X?"
* In-CLI docs are a cheaper version of man pages. In most cases, the output is larger than the current terminal size so you end up piping to a pager (where you can search as well), and now you have a more terse version of a man page. Why not just have a man page?
Man pages are useful because they have a standard format and layout, provide both short and long-form information, and are universally understood by almost anyone who has used a Linux machine in the past. "foo --help" requires the program to know what that means (I once managed to bootloop a router by doing "some_mgmt_cmt --help" and it didn't support "--help" -- I always use man pages now). One of the first things I teach students I tutor (when they're learning how to use Linux) is how to read man pages. Because they are the most useful form of information on Linux, and it's quite sad that so many new tools decide that they aren't worth the effort -- because you're now causing a previously unified source of information (man pages) to be fractured for no obvious gain.
I still add support for "--help" for my projects (because it is handy, I will admit) but I always include manpages for those projects as well so that users can actually get proper explanations of what the program does.
> I'm genuinely curious as I've never had anyone request man pages in our CLI.
Honestly, I would consider not using a project if an alternative had man pages (though in this case it would be somewhat more out of principle -- and I would submit a bug report to bring it to the maintainers' attention).
Personally, I still pull up "man git-pull" or similar. I'm actively annoyed that I have to remember that the AWS CLI is different in this regard.
Not to mention that using "--help" for man pages requires I open up a separate window when I typically just want a quick reference to the most used flags.
Moving man pages to a different command is like coming up with an alternative icon to the hamburger menu for your regular UI. Sure, all the functionality is still there, but it requires a full stop and search to remember where to find it.
I also prefer manpages over web searches for multiple reasons:
- works without internet: very important when you want to use a long train ride to write some code (I also have the entire rust-doc and all IETF RFCs on my disk for quick referencing)
- quick and reliable access to known items: `man ascii` is way quicker than finding an ASCII table on the web (probably on Wikipedia). And finding the syntax for an obscure bash feature is way easier when your search is confined to `man bash` rather than to the entire web.
- Don't know how to label this, but I like that the manpage is a complete documentation of one tool, unlike a disconnected set of Stack Overflow questions. That allows one to cursory read through the manpage to learn the scope of what that tool can accomplish.
One more reason - the man pages will be specific to the version of your tool. My man pages on my mac will automatically pull up the BSD version of "ls", not the GNU version.
I for one prefer actual manpages than online documentation. The web documentation is cumbersome to find, forces me to open a browser window, and I cannot copy-paste easily from inside my terminal.
Notice that if you already have help, you can build the manpages automatically from them using "help2man". You could get manpages for all your tools by simply adding a line into your makefile!
The end result argues against using help2man and thinking that --help and the user manual should be the same thing, not against having a user manual at all. (-:
Well, man pages are the standard way to get documentation. Sometimes --help is detailed enough to be a replacement (in which case I can tolerate the lack of man pages), but usually not.
I don't really care about documentation on the web. In fact I'd rather you simply treat the man pages as the single source of truth and put the man pages on the web. Sort of like https://linux.die.net/man/
I see no benefit whatsoever to web docs over man pages. man pages are immediately available, where you are (the CLI) without an internet connection or a web browser.
I expect the -h flag to give me a summary of the flags and arguments, to remind me of the particular name of the flag I'm missing. I most certainly don't want the whole documentation there, partly because the whole documentation is (presumably) large enough to scroll my history off screen.
So, yes, man pages are definitely more important than web or in-cli docs.
In my limited experience, manpages give you a wall of text when 9/10 times you just want a oneliner example of how to do something. Web resources generally address the lack of real world examples in manpages.
Then you use your pager's search functionality and go to the EXAMPLES section. If there is no EXAMPLES section, that's not the fault of the format, but of the author. Presumably, the same author would be equally good (or bad) at providing examples no matter if the target format was a man page or a web page.
I prefer a well-written man page to any other information. Git (and a few others) do open the man page when invoking `--help`. That's a way to avoid some overhead.
The fact they don't run on windows means some subset of your users cannot even use them if they wanted to. Better to spend your time on something they can all read.
I'm not saying they're not useful. If you've got plenty of time to write up docs, go ahead, but the reality is we only have so much time and I think we should spend our time writing in-CLI docs and web docs before we start man pages.
Also, you don't need web access to use in-CLI docs either, and that works on all platforms.
Having said this, I do plan on having man pages be an export type of the oclif docs (which is currently in-CLI and markdown). I intentionally made the output very similar to man pages already so it should be relatively easy to do.
For man pages you could suggest writing markdown and using a build process to automatically generate man pages [1] in the event they aren't using oclif. EDIT: I think we've all been in areas without network access like on a plane and not having a man page in that scenario is very annoying.
Also, you briefly say a few things about CLI apps using a remote API, you may want to add to that and say a few things about the proxy environment variables [2]. These are indispensible for corporate users. I think some early, early version of npm didn't respect the no_proxy environment variable, and for the http_proxy and https_proxy it required some arcane combination of: proxy in a flag, proxy in a config file, proxy environment variable set. It really should be an OR not an AND...
Last but not least, another annoying thing was tools changing their config format or location. I think it was docker that changed their config file format and/or location like two or three times. Absolutely infuriating.
Oh believe me. I'm intimately familiar with proxies and CLI apps. I think that might be a good standalone article though as it only applies to CLIs that connect to APIs whereas this article is intended for all CLIs, period. (Minus that note about the user-agent I suppose).
We get away without using any config files in the Heroku CLI which is certainly preferable. (Well, there is a config file, but I don't think anyone's using it and it's undocumented. I think all it can do is disable colors) Config is another topic that I do think would warrant its own article as well. I may not be the best author though as we've tried to avoid config. (Though it's a common enough problem I do want to solve generically as possible in oclif).
As far as automatically building man pages, I still think that's a wasted effort. Nobody has ever asked for or even mentioned man pages in our CLI. Setting up a build process and distribution is considerable effort and maintenance burden.
Of course if the users of your CLI want man pages then of course build them. In my experience though, that's not what users want. Though it's important to note that a CLI that interacts with a cloud service is pretty useless without internet.
If no internet is the only compelling reason to support man pages, I'm still not convinced it's a better use of your time. The docs should already be available offline in the CLI itself.
Greeks didnt invent philosophy, technically. The western tradition, maybe, but not the whole itself. And most of them, Socrates included, talked about thw gods a lot of the time. In fact, socrates's way of living a good life is, more or less, the same idea behind the christian heaven and hell concept. the only thing that really changes is, once most philosophers become theologians, they develop advanced theories in trying to explain away the Trinity or the Eucharist.
If you go look at Eastern philosophy, to this day it looks similar to how you're describing Socrates. Philosophy couldn't completely separate from theology back in Socrates' day but in later Greek writings you see the split fully manifest.
In one relatively small collection of nations, a mode of thought that was completely novel to the rest of the world was dreamed up. That way of thinking completely changed the world, so much that that way of thinking seems totally normal today.
When modern theological philosophers try to explain the Trinity, they use Greek ideas. In fact, the whole idea of the Trinity just falls out of a philosophical way of looking at it. The Eastern Christian Church doesn't use the doctrine.
Any time we talk about "the West," we're talking about a way of looking at things that originated with ancient Greece.
I read The Trial, and I am an avid reader of literary fiction. I understand that the trial was published posthumously, and against Kafka's wishes. These facts track, for me, because I feel The Trial was unfinished, unpolished, and most of the time, not very good.
The whole time Joseph K. expounds his innocence, but still acts a total jerk to everybody he can, and at every opportunity. Being a jerk isn't exactly a crime, but its never clear what level of law the novel is operating on, and so its wholly reasonable to suspect K. is completely guilty, which changes the whole narrative (and for the worse)
The first chapter is wonderful and all that good "Kafkaesque" material people harp on about. Then the meeting with the priest where Kafka essentially provides a dialogue and commentary on one of his own short stories; enlightening, and entertaining. But past that nothing jives right.
The knowledge of his hecka abusive father doesnt serve the novel either. From the real world information, it only takes a few small adjustments to make The Trial as an allegory for child abuse, and the rationalizations and bitter remorse associated with it into adulthood. Kafka, as a person, was treated terribly for little to no reason, by an authority he was subject to. Kafka assumes his innocence, and presumes the authority was wrong, until eventually his mind is beaten down enough and the abused believes that the abuse is deserved. Not to mention the natual tendancy to assume parents, even abusive ones, arent actually as bad as they seem (to a child, at least). Goven tvat reading, the mystery of interpreting The Trial dissapates, and a grim and more common than desired account remains.
I guess my frustration with The Trial is not the novel itself, or Kafka himself, but the circumstances of its publication (which, again, in its shambolic presentation, show), and of the "prediction of future bueraucracy" ascribed to it, both factors external to the author.
But on subject, kafka is sorta funny. In a dark and/or cynical way. But I find him more sad and pitiful, both his work anf the author himself.
before the change, on those days when it seems like nothing is happening, those people are thinking around the change. constantly, subconsciously (or not) and internally weighing options and possibilities. then, one day, they say "Im done." they find the words needed to make the change, which until then were elusive and, like a key, finding them makes the action doable, and doable without opposition. like a analog-to-digital switch that activates only when the analog portion is in the last 10% of either direction, the pwrson has their finger on the switch for days weeks months before the pressure builds up and things change.
this hypothesis excludes changes made in reaction to other external or involuntary changes in a persons life.
Well, first, use a logic programming language and report back. Then understand that math is almost wholly non-empirical. The things discovered or made up in math are not reflective of the real world, most of the time, regardless of how closely it resembles.
Take for instance euclidean geometry. In the world of equations, everything works. But a point, or a line, are neither things that exist out in the world, much less their relations which, when drawn on the surface of the earth, are probably not actually euclidean at all.
Number theory in particular is almost never about math, but about the patters mathematicians believe they recognize. Somebody a'ong the lines goes "oh hey check out this flower. I bet this is the only flower of this type in the world" and then spend hundreds of years trying to prove it.
A similar thing happened when Last.fm did their huge redesign. The new website was all js now, and they quit all support on the forums, messaging, pretty much all the old ways of communication between users. And for me, that was awful, since i was a part of a music collective that communicated primarily on those forums. After that everybody dispersed.
So outrage at a redesign is not always unfounded or silly. Web companies tend to hide things in them.