1. 29
    1. 3

      Terrific project. I love this.

      Fwiw while it looks good on my laptop, it didn’t work well on mobile (iphone, safari). The TOC didn’t work, and the margins were about 1/3 of the page on each side, so the content was squished into a thin band down the middle.

      1. 3

        And I fixed the TOC menu for mobile too.

      2. 3

        Thanks. I just forgot to test that. I tested it with w3m and lynx, but forgot to test with phone. Priorities, ’ey ;-)

        I fixed the padding, need to look at the TOC some other time.

    2. 1

      Nice work!

      I still can’t get past his “Silence is golden” admonishment. It’s utter crap. Every process should have a meaningful return code. Knowing that the third tool from the left in a giant pipeline produced no output or errors is exactly NOT helpful in any way.

      1. 11

        With respect, I think this is a misunderstanding. SIG is fine with return code. 0 means success. That’s silence.

        If you need to produce errors, then definitely produce them on stderr, but don’t mix them into stdout.

        If you want to provide status information, it should be an option, not a default. By default, you have silence on success. This puts the user in control and keeps them from being swamped by what every *tool( thinks is important.

        1. 4

          That makes a lot fo sense to me. This may be one of those instances where sloppy coders interpret a rule the way they want to.

          I’ve just been very badly burned by people who quote this and take it to mean that as long as their program produces nothing on stdout or stderr it should be seen to have succeeded, and they can set the return code to garbage or have it come back no zero on success.

          1. 4

            Ouch. Yes, that’s bad.

      2. 6

        no output or errors

        If there’s an error, it should output stuff. That’s actually one of the other rules:

        Rule of Repair: When you must fail, fail noisily and as soon as possible.

        Software should be transparent in the way that it fails, as well as in normal operation. It’s best when > software can cope with unexpected conditions by adapting to them, but the worst kinds of bugs are those in which the repair doesn’t succeed and the problem quietly causes corruption that doesn’t show up until much later.

        As with all “rules”, common sense applies of course. I think the biggest issue is just useless output that obscures actual useful stuff. I wrote a bit of a rant on apt-get a few years ago; probably not my best article, but it does make some good points IMHO, among which:

        $ sudo apt-get remove emacs24
        Reading package lists... Done
        Building dependency tree
        Reading state information... Done
        The following extra packages will be installed:
          emacs24-lucid xaw3dg
        The following packages will be REMOVED
          emacs24
        The following NEW packages will be installed
          emacs24-lucid xaw3dg
        0 to upgrade, 2 to newly install, 1 to remove and 0 not to upgrade.
        Need to get 3,534 kB of archives.
        After this operation, 531 kB of additional disk space will be used.
        Do you want to continue? [Y/n]
        

        Do you see the problem here? Sandwiched in between a lot of useless info is the information that:

        The following extra packages will be installed:
          emacs24-lucid xaw3dg
        

        Which is really unexpected, but also hard to miss in this big wall o’ text if you’re not carefully reading everything. Since apt-get always output walls of texts users tend to skim over it a bit too quick (I do, anyway).

        I once removed the wireless drivers on my Dell XPS by accident; it shipped with Ubuntu by default, but with extra Dell packages for the drivers. It was a pain to fix.

        There is much more to be said about this, but terminals are user interfaces, and text programs require careful UX design. Burdening the user with loads of informational messages by default is usually not a good idea.

        That said, a -v switch for verbose output to aid debugging is usually a good thing. The book discusses that too if I recall correctly.

      3. 6

        I think this is about superfluous output. For example consider rm. Imagine if it said something like :

        $ rm *
        Deleteing file "file1.txt"
        Successfully deleted file "file1.txt"
        Deleting file "file2.txt"
        Successfully deleted file "file2.xt"
        Done
        

        Unix philosophy recommends that this should be avoided

        1. 1

          That’s a really good point, and I totally get that. Like I said in a previous reply, I think the way the rule is written tends to encourage sloppy coders in their sloppy behavior, but the intent is good.

    3. 1

      This is great. Now the next step, who is going to typeset it in TeX?

    4. 1

      I was going to complain that you removed the table of contents but now I see that the TOC was hidden behind an arrow button the upper left corner. Since it’s one big page already, is there any reason not to just put the TOC at the start of the document?

      Anyway, I’m not here to nit-pick, just wanted to say nice work. TAOUP should be a must-read for every developer. Whether if you work on mainframes, embedded microcontrollers, or web front-ends, the core tenets of the philosophy are applicable to all software development.

      1. 1

        The idea is that you can use the TOC even when you’re somewhere in the document already, without having to scroll up (it also keeps track of where you are already, by highlighting that chapter).

        I find technical eBooks kinda annoying to read in a way, as it’s harder to skip back to a previous paragraph and such. I don’t really have a good solution to this, but this is my half-arsed attempt at making i at least a wee bit better.