5 ms·

I think the library is great, and don't have a whole lot to say about it, but wanted to mention one tangentially related thing: The README on this repo is awes

by dmunoz 13y ago

I think the library is great, and don't have a whole lot to say about it, but wanted to mention one tangentially related thing: The README on this repo is awesome. Opening up with advantages and disadvantages? Awesome. Plenty of code examples covering all of the major use cases? Awesome. Quick overview of the internals? AWESOME! Quick two line note about how to use the library in your project? Awesome. I'm tempted to rant about how I wish documentation was taken more seriously, and that programmers seem to make it a point of pride that spending the first half hour with a library figuring out how to actually use it is just something we have to deal with as programmers, but I won't do so aside from this single sentence.

wting 13y ago
man pages used to be treated with the same reverence, but nowadays nobody seems to bother. I have pretty extensive man pages for some of my open source stuff, but it doesn't seem to help with users downstream.
- deeviant 13y ago
  To be honest, I pretty much hate man pages. They almost never have examples(Is that some sort of rule?), they have no "quick summary of the shit you use 95% of the time", and they get generally written as a novel, seemingly from the perspective of the developer of the util rather than consumer. Mind you, I have used man pages many times before, but only because it was the best source of information, not because it was a particularly efficent one. The Markdown README of this string library is a thousand times better than any man page I have seen.
  - ploxiln 13y ago
    man pages start with the function prototypes, that's your "quick summary". Near the end there can be an examples section, and many man pages have one. If I run "man 3 open" I see a reasonable examples section. I like manpages because I'm already editing or running programs in the terminal, and I can pop open the man page in the terminal quite quickly and conveniently, without a search online or even a single network request, without reaching for the mouse, etc.
  - raverbashing 13y ago
    Man pages are bad but mostly useful INFO pages on the other hand, are terrible. Is there something less intuitive than the Info reader? Navigation is awful I think the RHIDE IDE had a better Info reader, IIRC, that one was useful.
    - sdegutis 13y ago
      I'm not sure it was ever meant to be intuitive or easy to use. As far as I can tell, INFO pages (and much of UNIX) was intended to be a stop-gap solution until something better and more permanent was written atop them. Unfortunately that dream was never realized, and Linux's accidental popularity standardized what was supposed to be a bunch of building blocks. I could be wrong though, but almost every utility in UNIX screams this to me.
      - dalke 13y ago
        I don't have the same understanding. Quite the opposite. GNU texinfo was designed (in 1986) to both generate manuals and be used as a hypertext system. I know of nothing in its history to suggest that it was a stop-gap system.
      - DougMerritt 13y ago
        INFO is a Richard Stallman thing, it's a GNU thing, it is emphatically NOT a Unix thing. Stallman wanted to replace the Unix thing (which was always man pages) with INFO, and for many years deprecated man pages, which is part of why many GNU man pages are sub-par. Not that non-GNU man pages are perfect, but still. As for Unix being intended to be a stop-gap, your impression is simply historically incorrect, aside from philosophical issues like the claims made in the infamous Gabriel essay "Worse is Better". > I could be wrong though, but almost every utility in UNIX screams this to me. Unix/Linux is certainly not perfect, but this simply reflects the truth of Henry Spencer's aphorism, "Those who don't understand Unix are condemned to reinvent it, poorly." People who think Unix got it all wrong, as opposed to merely having assorted warts, should read Raymond's "Art of Unix Programming". I was more than a little startled that Raymond captured a lot of the truth of the subject; it's a good read, and can potentially make anyone a better programmer. Edit: a more concise starting point: http://en.wikipedia.org/wiki/Unix_philosophy http://en.wikipedia.org/wiki/Unix_philosophy
  - dmm 13y ago
    Come try OpenBSD sometime. They take man pages seriously. http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
  - dllthomas 13y ago
    "They almost never have examples(Is that some sort of rule?)" They often have examples, though this is certainly better represented in some areas than others. One I looked at just the other day, man 7 aio, is 334 lines. Starts out describing the various aio functions and structures under DESCRIPTION, and has an EXAMPLE section: http://man7.org/linux/man-pages/man7/aio.7.html http://man7.org/linux/man-pages/man7/aio.7.html Or, also off the top of my head, man 2 signalfd, 196 lines with example code: http://man7.org/linux/man-pages/man2/signalfd.2.html http://man7.org/linux/man-pages/man2/signalfd.2.html Certainly there are man pages that aren't up to snuff (fix 'em!) but good man pages exist and many are great!
- clarry 13y ago
  Don't get discouraged; people who greatly appreciate a well written man page are still around. They're the users you might not hear about because the fine documentation actually helped them. :-)
  - aleem 13y ago
    I used to be quite okay with command line help for small tools, but ever since I discovered http://explainshell.com/ http://explainshell.com/ I have a new found appreciation for man pages.
  - busterarm 13y ago
    Very much this. To the parent commenter, THANK YOU! /signed someone who uses man pages all the time and seriously appreciates ones that have had thought put into them.
- Theriac25 13y ago
  That would be because GNU decided that man pages weren't good enough for them and decided to use info pages.
- sdegutis 13y ago
  Github READMEs in Markdown are the new man-pages.
  - DougMerritt 13y ago
    Which is unfortunate, because the majority are either extremely terse, and/or merely consist of installation instructions, so that the information content is nowhere near as high as an average man page. At least in my experience; maybe I've just been repeatedly unlucky. I doubt it, though, because there isn't any standard template for them, unlike the situation for man pages, which have a number of standard sections that people generally copy.

by dmunoz 13y ago

wting 13y ago

man pages used to be treated with the same reverence, but nowadays nobody seems to bother. I have pretty extensive man pages for some of my open source stuff, but it doesn't seem to help with users downstream.

deeviant 13y ago
To be honest, I pretty much hate man pages. They almost never have examples(Is that some sort of rule?), they have no "quick summary of the shit you use 95% of the time", and they get generally written as a novel, seemingly from the perspective of the developer of the util rather than consumer. Mind you, I have used man pages many times before, but only because it was the best source of information, not because it was a particularly efficent one. The Markdown README of this string library is a thousand times better than any man page I have seen.
- ploxiln 13y ago
  man pages start with the function prototypes, that's your "quick summary". Near the end there can be an examples section, and many man pages have one. If I run "man 3 open" I see a reasonable examples section. I like manpages because I'm already editing or running programs in the terminal, and I can pop open the man page in the terminal quite quickly and conveniently, without a search online or even a single network request, without reaching for the mouse, etc.
- raverbashing 13y ago
  Man pages are bad but mostly useful INFO pages on the other hand, are terrible. Is there something less intuitive than the Info reader? Navigation is awful I think the RHIDE IDE had a better Info reader, IIRC, that one was useful.
  - sdegutis 13y ago
    I'm not sure it was ever meant to be intuitive or easy to use. As far as I can tell, INFO pages (and much of UNIX) was intended to be a stop-gap solution until something better and more permanent was written atop them. Unfortunately that dream was never realized, and Linux's accidental popularity standardized what was supposed to be a bunch of building blocks. I could be wrong though, but almost every utility in UNIX screams this to me.
    - dalke 13y ago
      I don't have the same understanding. Quite the opposite. GNU texinfo was designed (in 1986) to both generate manuals and be used as a hypertext system. I know of nothing in its history to suggest that it was a stop-gap system.
    - DougMerritt 13y ago
      INFO is a Richard Stallman thing, it's a GNU thing, it is emphatically NOT a Unix thing. Stallman wanted to replace the Unix thing (which was always man pages) with INFO, and for many years deprecated man pages, which is part of why many GNU man pages are sub-par. Not that non-GNU man pages are perfect, but still. As for Unix being intended to be a stop-gap, your impression is simply historically incorrect, aside from philosophical issues like the claims made in the infamous Gabriel essay "Worse is Better". > I could be wrong though, but almost every utility in UNIX screams this to me. Unix/Linux is certainly not perfect, but this simply reflects the truth of Henry Spencer's aphorism, "Those who don't understand Unix are condemned to reinvent it, poorly." People who think Unix got it all wrong, as opposed to merely having assorted warts, should read Raymond's "Art of Unix Programming". I was more than a little startled that Raymond captured a lot of the truth of the subject; it's a good read, and can potentially make anyone a better programmer. Edit: a more concise starting point: http://en.wikipedia.org/wiki/Unix_philosophy http://en.wikipedia.org/wiki/Unix_philosophy
- dmm 13y ago
  Come try OpenBSD sometime. They take man pages seriously. http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
- dllthomas 13y ago
  "They almost never have examples(Is that some sort of rule?)" They often have examples, though this is certainly better represented in some areas than others. One I looked at just the other day, man 7 aio, is 334 lines. Starts out describing the various aio functions and structures under DESCRIPTION, and has an EXAMPLE section: http://man7.org/linux/man-pages/man7/aio.7.html http://man7.org/linux/man-pages/man7/aio.7.html Or, also off the top of my head, man 2 signalfd, 196 lines with example code: http://man7.org/linux/man-pages/man2/signalfd.2.html http://man7.org/linux/man-pages/man2/signalfd.2.html Certainly there are man pages that aren't up to snuff (fix 'em!) but good man pages exist and many are great!
clarry 13y ago
Don't get discouraged; people who greatly appreciate a well written man page are still around. They're the users you might not hear about because the fine documentation actually helped them. :-)
- aleem 13y ago
  I used to be quite okay with command line help for small tools, but ever since I discovered http://explainshell.com/ http://explainshell.com/ I have a new found appreciation for man pages.
- busterarm 13y ago
  Very much this. To the parent commenter, THANK YOU! /signed someone who uses man pages all the time and seriously appreciates ones that have had thought put into them.
Theriac25 13y ago
That would be because GNU decided that man pages weren't good enough for them and decided to use info pages.
sdegutis 13y ago
Github READMEs in Markdown are the new man-pages.
- DougMerritt 13y ago
  Which is unfortunate, because the majority are either extremely terse, and/or merely consist of installation instructions, so that the information content is nowhere near as high as an average man page. At least in my experience; maybe I've just been repeatedly unlucky. I doubt it, though, because there isn't any standard template for them, unlike the situation for man pages, which have a number of standard sections that people generally copy.