Subject: Re: Suggestions for newbie accessibility

From: Sergey Matveev <[email-masked]>
Date: Mon, 24 Jan 2022 01:45:57 +0300

*** John Goerzen [2022-01-23 15:38]:
>Most people have no need for make, or things like it, anymore. Basically
>every language ecosystem except C/C++ have their own build tools now, which
>are widely used.

Make and redo are used not only for development. Actually I used make
(now redo) a magnitude times more for non-programming tasks. Those tasks
are not disappeared. So the claim about "no need for make" (I interpret
"make" as some kind of dependency tracking, build automation tool) sounds
strange for me. For example Go has *some* built-in build automation
capabilities, but they are definitely not enough for very many things,
so likely you will have "external" build automation anyway. gVisor has
Bazel targets in its Go code -- that is one of the reasons I moved to
inet.af/netstack that automatically "applied" it.

>If somebody "just wants to install NNCP" and gets instructions that get in
>the way of that, it sours them on both redo and NNCP. Not beneficial for any
>goals.

What kind of instructions and what kind of detalization people expect?
Should I write about "apt install make go whatever", "yum install ...",
"pkg ...", etc? Should I write about adding new third-party repositories
for old OS distributions, what millions of people may still have installed?
I doubt that.

I saw two kind of extreme solutions: one is just to be completely silent
about anything how to build the program, just leave CMake and expect
that user has enough knowledge how to invoke and use it. Another is to
create several hundred shell (often actually bash) script to execute it
via curl ... | sudo bash, for maximal user's convenience (as they
claim). I find that solutions not good at all. Golden mean is better.

In most cases, if someone uses Make, then he just writes "make target"
in its installation documentation. In most cases people write on GNU
Make dialect. In all that most cases it won't work on BSD systems, where
"make" is not "gmake". And I think it is ok not to bother about that
kind of differences -- you just have to only mention what exact Make
implementation/dialect you use, and then it is user's problems how to
satisfy that requirement. If software uses CMake, it does not have to
describe how to use OS'es package manager. It is too much wasted time.
Note "if you are not on GNU OS, then probably you should additionally
install GNU Make and invoke it through gmake command" is enough.

I did the same: I describe what build commands you need to do. I do not
know if person has redo installed, what kind of redo and how he can
install it in his OS of choice. I added note about implementations I
have touched and seen them working. I even added some kind of dummy
fallback variant if someone does not want to install anything
additionally to his system (like m4 or other libraries/utilities go
inside many GNU tarballs too). You should use "redo" -- that is all.
What exact implementation -- it is user's choice.

"I do not want to read anything, I just want to copy-paste and press
Enter" -- I won't help that kind of users, who just ruin their and
others security, with permanent blind curl|bash-ing/docker-run-ing and
not knowing anything happening with their computer.

>not giving a straightforward recipe by default can be detrimental.

I quote the part from "Build instructions":

    $ [fetch|wget] http://www.nncpgo.org/download/nncp-8.3.0.tar.xz
    $ [fetch|wget] http://www.nncpgo.org/download/nncp-8.3.0.tar.xz.sig
    $ gpg --verify nncp-8.3.0.tar.xz.sig nncp-8.3.0.tar.xz
    $ xz --decompress --stdout nncp-8.3.0.tar.xz | tar xf -
    $ cd nncp-8.3.0
    $ redo all

    After that you should get various bin/nncp-* binaries and
    bin/hjson-cli command (only for your convenience, not necessary
    installation). For example, documentation for nncp-bundle command
    can be get with info doc/nncp.info -n nncp-bundle.

    It uses redo build system for that examples. You can use one of its
    various implementations, or at least minimalistic POSIX shell
    contrib/do (just replace redo with contrib/do in the example above)
    included in tarball. [...]

    There is install target respecting $DESTDIR. It will install
    binaries and info-documentation:
        # PREFIX=/usr/local redo install

Are not they enough? Someone has neither fetch, nor wget out-of-box.
Someone has no GnuPG. Someone may lack "xz". Someone will lack "redo".
There are many distributions, many operating systems, many setups, that
you can never fully cover. Current documentation in my opinion
explicitly hints about download, signature verification (with separate
page how to get public key. If person does not know what is it, then
probably he should not bother about its verification), decompression,
running build command, what output is expected (binaries, .info), what
build system is used, what implementations of it can be used, how you
can try to install them under root. And before all of that note about
Debian/Ubuntu "apt ... golang" and FreeBSD "pkg install", which at least
give hints how the package can be named in real life (however personally
I do not use binary packages downloaded from the Internet at all). And
there is explicit mention that you can just "replace redo with
contrib/do" as a fallback variant, that at least will be built
sequentially, without utilizing multiple CPUs. I even believe that "tar
xf nncp.tar.xz" will work in practice everywhere, but write about robust
xz|tar. What next? We should write people that they have to start shell
interpreter by running terminal emulator, that can be found through some
"Start" button?

>I am thinking I may write up something and post it somewhere, and give you
>permission to copy as much of it as you want for the NNCP manual, if that
>sounds good.

Would be good! Similarly like I copied your instructions about Exim+NNCP
setup some time ago, that was valuable.

>The regexp in Yggdrasil is indeed nice.  I don't know how easy it would be
>to do that in NNCP.

Well, it is trivial to add (you need just to add regexp applied to
net.Interfaces() output :-)), however seems it is useful only for using
as a default option. But I do not mind against it -- it won't break any
existing configuration files.

>An alternative might be a special token that would
>indicate "ALL".

".*" as in Yggdrasil is more than enough.

>Interface names are not particularly persistent these days
>and what is present when cfgnew is run may not be what's there later.

Actually I saw non-persistent interface names only on GNU/Linux boxes.
All *BSDs I touched have them more than immutable even when changing
hardware in most cases :-). But agreed that, especially various
tun/tap/bridge/vtnet/etc, are dynamic.

-- 
Sergey Matveev (http://www.stargrave.org/)
OpenPGP: CF60 E89A 5923 1E76 E263  6422 AE1A 8109 E498 57EF