What is Nix and why you should try it

these functions' documentation is either buried in a long manual

This is a problem with lots of feature-rich software, even with meticulously-documented APIs. What we need is reverse-indexed documentation. That is, an extensive API reference is only useful for someone who already knows what functions are in the API and just needs to remember how to use them. But even the most thorough API reference does nothing to promote discovering new functionality. This is often left to the authors, who then have to go about writing a User's Guide that gradually explains concepts, idioms, etc. in prose.

Thorough User's Guides are rare because they are tough to write, and even tougher to write well. Users don't often have the time to read through potentially hundreds of pages of prose to find what they're looking for. We need a better way to let users search or browse for concepts, and then be given a list of the functions that implement each concept.

That is, addition to documentation like:

    size_t strlen(const char * s);
      RETURN: Length of string s.

    size_t strnlen(const char * s, size_t maxlen);
      RETURN: Length of string s, or maxlen (whichever is smaller).
      NOTE: Stops reading after maxlen.

    char * stpcpy(char * dst, const char * src);
      Copy src to dst.
      RETURN: pointer to trailing '\0' of dst, or dst[n] if no trailing NUL.
      NOTE: Undefined behavior if dst and src overlap.

    char * stpncpy(char * dst, const char * src, size_t len);
      Copy up to len bytes from src to dst.
      RETURN: pointer to trailing '\0' of dst, or dst[n] if no trailing NUL.
      NOTE: Undefined behavior if dst and src overlap.

    char * strcpy(char * dst, const char * src);
      Copy src to dst.
      RETURN: dst.
      NOTE: Undefined behavior if dst and src overlap.

    char * strncpy(char * dst, const char * src, size_t len);
      Copy up to len bytes from src to dst
      RETURN: dst.
      NOTE: Undefined behavior if dst and src overlap.

We also need to be able to "tag" functions. So we might have the following tags that allow us to search for concepts:

    strcpy
      TAGS: "concept":"data type":"text", "concept":"attribute":"length",
            ".input":"array", ".input":"char", ".input":"pointer",
            ".return":"string", ".return":"pointer"
    strncpy
      TAGS: "concept":"data type":"text", "concept":"attribute":"length",
            "concept":"data type":"array":"max-length operator",
            ".input":"array", ".input":"char", ".input":"pointer",
            ".return":"array", ".return":"pointer"

And a tag browsing page that looks like

    concept
    └─ data type
       └─ text
       └─ array (conceptual)
          └─ max-length operator
    └─ attribute
       └─ length / size
    data structure
    └─ char
    └─ array (implementation)
    └─ pointer
    

Which the user could then scan, and identify keywords to search for:

    '"concept":"data type":"text" AND "concept":"attribute":"length"'

And be given "strlen" and "strnlen" as the top two hits, followed by "wcslen" and "wcsnlen".

It seems like a PITA at first, but I'm pretty sure tagging functions in their docstrings is easier than writing a whole new User's Guide.

One great approach is the Hoogle search engine for Haskell [1]. The idea with that is that you search by type, instead of name. So if you were looking for a function to take a item, and return a list with n copies of that item, you would search for `a -> Int -> [a]`, which would give you back replicate.

Looks like the Nix expression language is untyped, so this wouldn't work directly, but maybe adding a rough type signature in the docstring would get some of those benefits (and it should be a bit better for discover-ability, since you wouldn't need to guess the same tags/concept the author choose).

[1] - https://www.haskell.org/hoogle/

Why not both? Does Homebrew conflict with Nix in such a way that only one is possible at a time?

I can definitely see giving Nix priority for work-related development, but I would like to know if Homebrew can still fill in as a backup option.

RhodeCode is one of projects that build their installer on top of nix package manager. Check out this blog post: https://rhodecode.com/blog/61/rhodecode-and-nix-package-mana...

This is good to know, though I continue to be sad that there isn't a general "design principles of package managers" knowledgebase.