* [TUHS] Another "craft" discussion topic - mindless tool proliferation @ 2017-09-19 17:01 Jon Steinhart 2017-09-19 17:05 ` Steve Nickolas ` (2 more replies) 0 siblings, 3 replies; 54+ messages in thread From: Jon Steinhart @ 2017-09-19 17:01 UTC (permalink / raw) OK, here's another one that's good for chest thumping... I am not a fan of texinfo. It doesn't provide any benefits (to me) over man. I suppose that it was trailblazing in that it broke manual pages up into sections that couldn't easily be viewed concurrently long before the www and web pages that broke things up into multiple pages to make room for more ads. Any benefits that texinfo might have are completely lost by the introduction of multiple non-intersecting ways to find documentation. This is a systemic problem. I have a section in my book-in-progress where I talk about being a "good programming citizen". One of the things that I say is: Often there is a tool that does most of what you need but is lacking some feature or other. Add that feature to the existing tool; don't just write a new one. The problem with writing a new one is that, as a tool user, you end up having to learn a lot of tools that perform essentially the same function. It's a waste of time an energy. A good example is the make utility (invented by Stuart Feldman at Bell Labs in 1976) that is used to build large software packages. As time went on, new features were needed. Some were added to make, but many other incompatible utilities were created that performed similar functions. Don't create burdens for others. Improve existing tools if possible. A funny example of this is when I was consulting for Xilinx in the late 80s on a project that had to run on both Suns and PCs. Naturally, I did the development on a Sun and ported to the PC later. When it came time to do the port, a couple of the employees proudly came to me and told me about this wonderful program that they wrote that was absolutely necessary for doing the PC build. I was completely puzzled and told them that I already had the PC build complete. They told me that that couldn't be possible since I didn't use their wonderful utility. Turns out that their utility wrote out all of the make dependencies for the PC. I, of course, wrote a .c.obj rule which was all that it took. They were excessively angry at me for inadvertently making them look like fools that they were. Another example is a more recent web-based project on which I was advising. I'm a big fan of jQuery; it gets the job done. Someone said "Why are you using that instead of angular?" I did a bit of research before answering. Turns out that one of the main reasons given for angular over jQuery was that "it's fresh". That was a new one for me. Still unclear why freshness is an attribute that would trump stability. So, I'm sure that many of you have stories about unnecessary tools and packages that were created by people unable to RTFM. Would be amused to hear 'em. Jon ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 17:01 [TUHS] Another "craft" discussion topic - mindless tool proliferation Jon Steinhart @ 2017-09-19 17:05 ` Steve Nickolas 2017-09-19 20:31 ` Pete Turnbull 2017-09-19 23:35 ` Theodore Ts'o 2017-09-20 18:15 ` Clem Cole 2 siblings, 1 reply; 54+ messages in thread From: Steve Nickolas @ 2017-09-19 17:05 UTC (permalink / raw) On Tue, 19 Sep 2017, Jon Steinhart wrote: > Another example is a more recent web-based project on which I was advising. > I'm a big fan of jQuery; it gets the job done. Someone said "Why are you > using that instead of angular?" I did a bit of research before answering. > Turns out that one of the main reasons given for angular over jQuery was > that "it's fresh". That was a new one for me. Still unclear why freshness > is an attribute that would trump stability. I see it all the time and call it "blinded by the leet". -uso. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 17:05 ` Steve Nickolas @ 2017-09-19 20:31 ` Pete Turnbull 2017-09-19 20:37 ` Warner Losh 0 siblings, 1 reply; 54+ messages in thread From: Pete Turnbull @ 2017-09-19 20:31 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 474 bytes --] On 19/09/2017 18:05, Steve Nickolas wrote: > On Tue, 19 Sep 2017, Jon Steinhart wrote: > >> Turns out that one of the main reasons given for angular over jQuery was >> that "it's fresh". That was a new one for me. Still unclear why >> freshness >> is an attribute that would trump stability. > > I see it all the time and call it "blinded by the leet". LOL! Yes, I come across that attitude all too often. I must remember that phrase :-) -- Pete Pete Turnbull ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 20:31 ` Pete Turnbull @ 2017-09-19 20:37 ` Warner Losh 0 siblings, 0 replies; 54+ messages in thread From: Warner Losh @ 2017-09-19 20:37 UTC (permalink / raw) On Tue, Sep 19, 2017 at 2:31 PM, Pete Turnbull <pete at dunnington.plus.com> wrote: > On 19/09/2017 18:05, Steve Nickolas wrote: > >> On Tue, 19 Sep 2017, Jon Steinhart wrote: >> >> Turns out that one of the main reasons given for angular over jQuery was >>> that "it's fresh". That was a new one for me. Still unclear why >>> freshness >>> is an attribute that would trump stability. >>> >> >> I see it all the time and call it "blinded by the leet". >> > > LOL! Yes, I come across that attitude all too often. I must remember > that phrase :- Don't you mean "Blinded by the 1337?" or is 1337-speak passed from cool into pase' now? Warner -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170919/0c4edac0/attachment.html> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 17:01 [TUHS] Another "craft" discussion topic - mindless tool proliferation Jon Steinhart 2017-09-19 17:05 ` Steve Nickolas @ 2017-09-19 23:35 ` Theodore Ts'o 2017-09-20 0:47 ` Lyndon Nerenberg ` (3 more replies) 2017-09-20 18:15 ` Clem Cole 2 siblings, 4 replies; 54+ messages in thread From: Theodore Ts'o @ 2017-09-19 23:35 UTC (permalink / raw) On Tue, Sep 19, 2017 at 10:01:57AM -0700, Jon Steinhart wrote: > OK, here's another one that's good for chest thumping... > > I am not a fan of texinfo. It doesn't provide any benefits (to me) over man. > > I suppose that it was trailblazing in that it broke manual pages up into > sections that couldn't easily be viewed concurrently long before the www and > web pages that broke things up into multiple pages to make room for more ads. If you take a look at how perl handles its man pages, with 188 man pages in section 1: ... perlsyn Perl syntax perldata Perl data structures perlop Perl operators and precedence perlsub Perl subroutines ... I find that info system, with its hypertext linking, to be far more convenient. I've occasionally wished that the perl documentation was available in info file format. But sometimes the extra complexity of, say, gdb or gmake, provides a lot of convenience. And the question is whether man is a sufficient way to provide documentation. I would humbly submit that the choice of using man pages as used by perl is an existence proof that man is *not* the optimal way to provide documentation for a sufficiently complex language or program. (If the answer is that Unix programs should never be that complicated; that's fine. But at least for me personally, I prefer to use gdb, with its texinfo/info files, over adb with its man page. If you want to argue that "real programmers" should be able to decipher structure layouts by looking at C structure declarations and creating adb macros by hand, and that DWARF annotations are for the weak and sickly, fair enough. :-) - Ted ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 23:35 ` Theodore Ts'o @ 2017-09-20 0:47 ` Lyndon Nerenberg 2017-09-20 1:02 ` Larry McVoy ` (2 more replies) 2017-09-20 6:20 ` Lars Brinkhoff ` (2 subsequent siblings) 3 siblings, 3 replies; 54+ messages in thread From: Lyndon Nerenberg @ 2017-09-20 0:47 UTC (permalink / raw) > On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso at mit.edu> wrote: > > If you take a look at how perl handles its man pages, with 188 man > pages in section 1: ... you quickly recognize the difference between a manpage (i.e. reference page) and a user manual. Perl's (and other's) attempts to pack a 200 page user guide into a block of manpages is a misuse of what manpages represent. texinfo was a good move in the direction towards online, cross-referenced, user documentation. But so often that lead to manpages that consisted of the single line "see the texinfo doc"; the documentation authors completely missing the point. --lyndon ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 0:47 ` Lyndon Nerenberg @ 2017-09-20 1:02 ` Larry McVoy 2017-09-20 1:09 ` Lyndon Nerenberg ` (2 more replies) 2017-09-20 16:45 ` Steffen Nurpmeso 2017-09-21 17:33 ` Tony Finch 2 siblings, 3 replies; 54+ messages in thread From: Larry McVoy @ 2017-09-20 1:02 UTC (permalink / raw) On Tue, Sep 19, 2017 at 05:47:42PM -0700, Lyndon Nerenberg wrote: > > > On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso at mit.edu> wrote: > > > > If you take a look at how perl handles its man pages, with 188 man > > pages in section 1: > > ... you quickly recognize the difference between a manpage (i.e. reference page) and a user manual. Perl's (and other's) attempts to pack a 200 page user guide into a block of manpages is a misuse of what manpages represent. > > texinfo was a good move in the direction towards online, cross-referenced, user documentation. But so often that lead to manpages that consisted of the single line "see the texinfo doc"; the documentation authors completely missing the point. +1. Man pages should be short things that remind you how to run the program. Putting a user guide in man pages is nuts, and in today's world texinfo is just as nuts. Put it on the web and move on. But don't give me the see texinfo man page, I hate that crap. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:02 ` Larry McVoy @ 2017-09-20 1:09 ` Lyndon Nerenberg 2017-09-20 1:13 ` Larry McVoy ` (3 more replies) 2017-09-20 2:07 ` Theodore Ts'o 2017-09-20 4:26 ` Grant Taylor 2 siblings, 4 replies; 54+ messages in thread From: Lyndon Nerenberg @ 2017-09-20 1:09 UTC (permalink / raw) > On Sep 19, 2017, at 6:02 PM, Larry McVoy <lm at mcvoy.com> wrote: > > Put it on the web and move on. My main gripe about that is that I can't read the web when the router I'm trying to install won't work, keeping me from the needed web documentation ... *Please* write your documentation in a way that allows you to generate (useful, readable!) PDF documents that I can download for offline viewing. Believe it or not, I don't haul along a 300 mile cat-5 cable when I go sailing. I still like to write code on the boat. So much for Go :-P And $GOD help everyone in the Caribbean trying to bootstrap their infrastructure right now. How is your https://... documentation going to help them out? --lyndon ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:09 ` Lyndon Nerenberg @ 2017-09-20 1:13 ` Larry McVoy 2017-09-20 1:22 ` Larry McVoy 2017-09-20 4:29 ` Grant Taylor ` (2 subsequent siblings) 3 siblings, 1 reply; 54+ messages in thread From: Larry McVoy @ 2017-09-20 1:13 UTC (permalink / raw) On Tue, Sep 19, 2017 at 06:09:27PM -0700, Lyndon Nerenberg wrote: > > > On Sep 19, 2017, at 6:02 PM, Larry McVoy <lm at mcvoy.com> wrote: > > > > Put it on the web and move on. > > My main gripe about that is that I can't read the web when the router I'm trying to install won't work, keeping me from the needed web documentation ... > > *Please* write your documentation in a way that allows you to generate (useful, readable!) PDF documents that I can download for offline viewing. Believe it or not, I don't haul along a 300 mile cat-5 cable when I go sailing. I still like to write code on the boat. So much for Go :-P > > And $GOD help everyone in the Caribbean trying to bootstrap their infrastructure right now. How is your https://... documentation going to help them out? Dude, you are talking to the guy who wrote webroff, a tool that takes -ms markup and puts on the web. Our website was done in webroff for years and you could take all the source and produce a pdf. I'm with ya. Where I get off the boat (heh) is texinfo, it was useful in its time, it sucks now. I actually prefer man pages to texinfo by a long shot. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:13 ` Larry McVoy @ 2017-09-20 1:22 ` Larry McVoy 2017-09-20 2:01 ` Larry McVoy 2017-09-20 16:49 ` Steffen Nurpmeso 0 siblings, 2 replies; 54+ messages in thread From: Larry McVoy @ 2017-09-20 1:22 UTC (permalink / raw) On Tue, Sep 19, 2017 at 06:13:40PM -0700, Larry McVoy wrote: > On Tue, Sep 19, 2017 at 06:09:27PM -0700, Lyndon Nerenberg wrote: > > > > > On Sep 19, 2017, at 6:02 PM, Larry McVoy <lm at mcvoy.com> wrote: > > > > > > Put it on the web and move on. > > > > My main gripe about that is that I can't read the web when the router I'm trying to install won't work, keeping me from the needed web documentation ... > > > > *Please* write your documentation in a way that allows you to generate (useful, readable!) PDF documents that I can download for offline viewing. Believe it or not, I don't haul along a 300 mile cat-5 cable when I go sailing. I still like to write code on the boat. So much for Go :-P > > > > And $GOD help everyone in the Caribbean trying to bootstrap their infrastructure right now. How is your https://... documentation going to help them out? > > Dude, you are talking to the guy who wrote webroff, a tool that takes -ms > markup and puts on the web. Our website was done in webroff for years and > you could take all the source and produce a pdf. Here's an example: http://www.mcvoy.com/lm/bkdocs/UG/ is the source, you can look at those files, they are nroff -ms source, and then look at http://www.mcvoy.com/lm/bkdocs/UG/tmp and you'll see the web version of the docs. Which is pretty useful. You've got all the .NH 1 headers in the table of contents down the left side, and when you click one of them it shows you the .NH 2, .NH 3 etc headers for just that section. And if you go to http://www.mcvoy.com/lm/bkdocs/UG/tmp/map.html you can get html versions of any .NH 1 section, or the entire thing as one page. It's a ~1700 line perl program (perl 4ish) and it has some ability to skin the content. Source in http://www.mcvoy.com/lm/bkdocs/UG/webroff ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:22 ` Larry McVoy @ 2017-09-20 2:01 ` Larry McVoy 2017-09-20 2:34 ` Bakul Shah 2017-09-20 16:49 ` Steffen Nurpmeso 1 sibling, 1 reply; 54+ messages in thread From: Larry McVoy @ 2017-09-20 2:01 UTC (permalink / raw) So there are links in that that don't work, that user guide is really old, but you should be able to get the idea. If people bitch about the links that don't work I'll see if I can fix them. The skinning is in the Html file. > Here's an example: > > http://www.mcvoy.com/lm/bkdocs/UG/ > > is the source, you can look at those files, they are nroff -ms source, > and then look at > > http://www.mcvoy.com/lm/bkdocs/UG/tmp > > and you'll see the web version of the docs. Which is pretty useful. > You've got all the .NH 1 headers in the table of contents down the > left side, and when you click one of them it shows you the .NH 2, > .NH 3 etc headers for just that section. > > And if you go to > > http://www.mcvoy.com/lm/bkdocs/UG/tmp/map.html > > you can get html versions of any .NH 1 section, or the entire thing as one > page. > > It's a ~1700 line perl program (perl 4ish) and it has some ability to skin > the content. Source in http://www.mcvoy.com/lm/bkdocs/UG/webroff -- --- Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 2:01 ` Larry McVoy @ 2017-09-20 2:34 ` Bakul Shah 2017-09-20 2:47 ` Larry McVoy ` (2 more replies) 0 siblings, 3 replies; 54+ messages in thread From: Bakul Shah @ 2017-09-20 2:34 UTC (permalink / raw) These days I use the markdown format more and more as it is easier and more readable than troff/LaTeX and good enough for this sort of documentation. There is even LaTeX package for it! > On Sep 19, 2017, at 7:01 PM, Larry McVoy <lm at mcvoy.com> wrote: > > So there are links in that that don't work, that user guide is really old, > but you should be able to get the idea. If people bitch about the links > that don't work I'll see if I can fix them. > > The skinning is in the Html file. > >> Here's an example: >> >> http://www.mcvoy.com/lm/bkdocs/UG/ >> >> is the source, you can look at those files, they are nroff -ms source, >> and then look at >> >> http://www.mcvoy.com/lm/bkdocs/UG/tmp >> >> and you'll see the web version of the docs. Which is pretty useful. >> You've got all the .NH 1 headers in the table of contents down the >> left side, and when you click one of them it shows you the .NH 2, >> .NH 3 etc headers for just that section. >> >> And if you go to >> >> http://www.mcvoy.com/lm/bkdocs/UG/tmp/map.html >> >> you can get html versions of any .NH 1 section, or the entire thing as one >> page. >> >> It's a ~1700 line perl program (perl 4ish) and it has some ability to skin >> the content. Source in http://www.mcvoy.com/lm/bkdocs/UG/webroff > > -- > --- > Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 2:34 ` Bakul Shah @ 2017-09-20 2:47 ` Larry McVoy 2017-09-20 6:18 ` Bakul Shah 2017-09-20 4:35 ` Grant Taylor 2017-09-24 23:03 ` Ralph Corderoy 2 siblings, 1 reply; 54+ messages in thread From: Larry McVoy @ 2017-09-20 2:47 UTC (permalink / raw) Yeah, markdown didn't exist at the time I did webroff and I like, still like, roff. It says what you want more than how you want to do it. On Tue, Sep 19, 2017 at 07:34:00PM -0700, Bakul Shah wrote: > These days I use the markdown format more and more as it is easier and > more readable than troff/LaTeX and good enough for this sort of documentation. > There is even LaTeX package for it! > > > On Sep 19, 2017, at 7:01 PM, Larry McVoy <lm at mcvoy.com> wrote: > > > > So there are links in that that don't work, that user guide is really old, > > but you should be able to get the idea. If people bitch about the links > > that don't work I'll see if I can fix them. > > > > The skinning is in the Html file. > > > >> Here's an example: > >> > >> http://www.mcvoy.com/lm/bkdocs/UG/ > >> > >> is the source, you can look at those files, they are nroff -ms source, > >> and then look at > >> > >> http://www.mcvoy.com/lm/bkdocs/UG/tmp > >> > >> and you'll see the web version of the docs. Which is pretty useful. > >> You've got all the .NH 1 headers in the table of contents down the > >> left side, and when you click one of them it shows you the .NH 2, > >> .NH 3 etc headers for just that section. > >> > >> And if you go to > >> > >> http://www.mcvoy.com/lm/bkdocs/UG/tmp/map.html > >> > >> you can get html versions of any .NH 1 section, or the entire thing as one > >> page. > >> > >> It's a ~1700 line perl program (perl 4ish) and it has some ability to skin > >> the content. Source in http://www.mcvoy.com/lm/bkdocs/UG/webroff > > > > -- > > --- > > Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm -- --- Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 2:47 ` Larry McVoy @ 2017-09-20 6:18 ` Bakul Shah 0 siblings, 0 replies; 54+ messages in thread From: Bakul Shah @ 2017-09-20 6:18 UTC (permalink / raw) I used *roff for man pages. Used to use man pages as brief functional specs for new commands. Worked very well. Even prior to 1985 I usually just kept plain text documents in a readable format (not unlike "markdown". Though, rather than # section, ## subsect I used separate ==== and --- lines). Most of my notes start out in that form and longer ones may get converted to latex files. But it's nice to have choices! BTW, Bitkeeper document looks pretty decent. > On Sep 19, 2017, at 7:47 PM, Larry McVoy <lm at mcvoy.com> wrote: > > Yeah, markdown didn't exist at the time I did webroff and I like, still > like, roff. It says what you want more than how you want to do it. > > On Tue, Sep 19, 2017 at 07:34:00PM -0700, Bakul Shah wrote: >> These days I use the markdown format more and more as it is easier and >> more readable than troff/LaTeX and good enough for this sort of documentation. >> There is even LaTeX package for it! >> >>> On Sep 19, 2017, at 7:01 PM, Larry McVoy <lm at mcvoy.com> wrote: >>> >>> So there are links in that that don't work, that user guide is really old, >>> but you should be able to get the idea. If people bitch about the links >>> that don't work I'll see if I can fix them. >>> >>> The skinning is in the Html file. >>> >>>> Here's an example: >>>> >>>> http://www.mcvoy.com/lm/bkdocs/UG/ >>>> >>>> is the source, you can look at those files, they are nroff -ms source, >>>> and then look at >>>> >>>> http://www.mcvoy.com/lm/bkdocs/UG/tmp >>>> >>>> and you'll see the web version of the docs. Which is pretty useful. >>>> You've got all the .NH 1 headers in the table of contents down the >>>> left side, and when you click one of them it shows you the .NH 2, >>>> .NH 3 etc headers for just that section. >>>> >>>> And if you go to >>>> >>>> http://www.mcvoy.com/lm/bkdocs/UG/tmp/map.html >>>> >>>> you can get html versions of any .NH 1 section, or the entire thing as one >>>> page. >>>> >>>> It's a ~1700 line perl program (perl 4ish) and it has some ability to skin >>>> the content. Source in http://www.mcvoy.com/lm/bkdocs/UG/webroff >>> >>> -- >>> --- >>> Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm > > -- > --- > Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 2:34 ` Bakul Shah 2017-09-20 2:47 ` Larry McVoy @ 2017-09-20 4:35 ` Grant Taylor 2017-09-20 5:54 ` Ian Zimmerman 2017-09-24 23:03 ` Ralph Corderoy 2 siblings, 1 reply; 54+ messages in thread From: Grant Taylor @ 2017-09-20 4:35 UTC (permalink / raw) On 09/19/2017 08:34 PM, Bakul Shah wrote: > These days I use the markdown format more and more as it is easier and > more readable than troff/LaTeX and good enough for this sort of documentation. > There is even LaTeX package for it! I've always found markdown to be limiting, and inconsistent. (Lack of standards?) I would rather put together documentation in raw HTML than markdown. But I've been accused of many (what others consider to be) nasty things. -- Grant. . . . unix || die ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 4:35 ` Grant Taylor @ 2017-09-20 5:54 ` Ian Zimmerman 0 siblings, 0 replies; 54+ messages in thread From: Ian Zimmerman @ 2017-09-20 5:54 UTC (permalink / raw) On 2017-09-19 22:35, Grant Taylor wrote: > > These days I use the markdown format more and more as it is easier > > and more readable than troff/LaTeX and good enough for this sort of > > documentation. There is even LaTeX package for it! > > I've always found markdown to be limiting, and inconsistent. (Lack of > standards?) There's also ReStructured Text, where the usage is more uniform, at least according to some. I write simple documents in it, such as my resume, blog posts, and yes, manpages :) -- Please don't Cc: me privately on mailing lists and Usenet, if you also post the followup to the list or newsgroup. Do obvious transformation on domain to reply privately _only_ on Usenet. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 2:34 ` Bakul Shah 2017-09-20 2:47 ` Larry McVoy 2017-09-20 4:35 ` Grant Taylor @ 2017-09-24 23:03 ` Ralph Corderoy 2017-09-24 23:35 ` Bakul Shah 2 siblings, 1 reply; 54+ messages in thread From: Ralph Corderoy @ 2017-09-24 23:03 UTC (permalink / raw) Bakul Shah wrote: > These days I use the markdown format more and more http://undeadly.org/cgi?action=article&sid=20170304230520 has some reasons to dislike Markdown. :-) -- Cheers, Ralph. https://plus.google.com/+RalphCorderoy ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-24 23:03 ` Ralph Corderoy @ 2017-09-24 23:35 ` Bakul Shah 0 siblings, 0 replies; 54+ messages in thread From: Bakul Shah @ 2017-09-24 23:35 UTC (permalink / raw) On Mon, 25 Sep 2017 00:03:08 +0100 Ralph Corderoy <ralph at inputplus.co.uk> wrote: Ralph Corderoy writes: > Bakul Shah wrote: > > These days I use the markdown format more and more > > http://undeadly.org/cgi?action=article&sid=20170304230520 > has some reasons to dislike Markdown. :-) Worse is better :-) Others can use what they want but Markdown works well enough for me. As always, if you use every last "feature" of a particular dialect, you will regret it. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:22 ` Larry McVoy 2017-09-20 2:01 ` Larry McVoy @ 2017-09-20 16:49 ` Steffen Nurpmeso 1 sibling, 0 replies; 54+ messages in thread From: Steffen Nurpmeso @ 2017-09-20 16:49 UTC (permalink / raw) Larry McVoy <lm at mcvoy.com> wrote: |On Tue, Sep 19, 2017 at 06:13:40PM -0700, Larry McVoy wrote: |> On Tue, Sep 19, 2017 at 06:09:27PM -0700, Lyndon Nerenberg wrote: |>> |>>> On Sep 19, 2017, at 6:02 PM, Larry McVoy <lm at mcvoy.com> wrote: |>>> |>>> Put it on the web and move on. |>> |>> My main gripe about that is that I can't read the web when the router \ |>> I'm trying to install won't work, keeping me from the needed web \ |>> documentation ... |>> |>> *Please* write your documentation in a way that allows you to generate \ |>> (useful, readable!) PDF documents that I can download for offline \ |>> viewing. Believe it or not, I don't haul along a 300 mile cat-5 \ |>> cable when I go sailing. I still like to write code on the boat. \ |>> So much for Go :-P |>> |>> And $GOD help everyone in the Caribbean trying to bootstrap their \ |>> infrastructure right now. How is your https://... documentation \ |>> going to help them out? |> |> Dude, you are talking to the guy who wrote webroff, a tool that takes -ms |> markup and puts on the web. Our website was done in webroff for years and |> you could take all the source and produce a pdf. | |Here's an example: | |http://www.mcvoy.com/lm/bkdocs/UG/ | |is the source, you can look at those files, they are nroff -ms source, |and then look at | |http://www.mcvoy.com/lm/bkdocs/UG/tmp | |and you'll see the web version of the docs. Which is pretty useful. |You've got all the .NH 1 headers in the table of contents down the |left side, and when you click one of them it shows you the .NH 2, |.NH 3 etc headers for just that section. | |And if you go to | |http://www.mcvoy.com/lm/bkdocs/UG/tmp/map.html | |you can get html versions of any .NH 1 section, or the entire thing as one |page. | |It's a ~1700 line perl program (perl 4ish) and it has some ability to skin |the content. Source in http://www.mcvoy.com/lm/bkdocs/UG/webroff That is pretty cool indeed. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt) ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:09 ` Lyndon Nerenberg 2017-09-20 1:13 ` Larry McVoy @ 2017-09-20 4:29 ` Grant Taylor 2017-09-20 6:43 ` Peter Jeremy 2017-09-20 16:48 ` Steffen Nurpmeso 3 siblings, 0 replies; 54+ messages in thread From: Grant Taylor @ 2017-09-20 4:29 UTC (permalink / raw) On 09/19/2017 07:09 PM, Lyndon Nerenberg wrote: > My main gripe about that is that I can't read the web when the router I'm trying to install won't work, keeping me from the needed web documentation ... *SO* *MUCH* *THIS*!!! > *Please* write your documentation in a way that allows you to generate (useful, readable!) PDF documents that I can download for offline viewing. Believe it or not, I don't haul along a 300 mile cat-5 cable when I go sailing. I still like to write code on the boat. So much for Go :-P I have a personal bias against PDF and prefer single (or few) page text / HTML files that I can easily consume offline. > And $GOD help everyone in the Caribbean trying to bootstrap their infrastructure right now. How is your https://... documentation going to help them out? *LOL* #truth -- Grant. . . . unix || die ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:09 ` Lyndon Nerenberg 2017-09-20 1:13 ` Larry McVoy 2017-09-20 4:29 ` Grant Taylor @ 2017-09-20 6:43 ` Peter Jeremy 2017-09-20 8:25 ` Bakul Shah 2017-09-20 16:48 ` Steffen Nurpmeso 3 siblings, 1 reply; 54+ messages in thread From: Peter Jeremy @ 2017-09-20 6:43 UTC (permalink / raw) On 2017-Sep-19 18:09:27 -0700, Lyndon Nerenberg <lyndon at orthanc.ca> wrote: >*Please* write your documentation in a way that allows you to generate >(useful, readable!) PDF documents that I can download for offline viewing. >Believe it or not, I don't haul along a 300 mile cat-5 cable when I go >sailing. I still like to write code on the boat. So much for Go :-P One of the really nice things about Go is that all the library source code and documentatin is installed by default and you can run a local instance of the documentation server on your laptop (or whatever). Likewise, the specification is one HTML page - if you really want, you could convert that to PDF but having all the hyperlinks is really handy. (I haven't tried running a local copy of the playground but that should be possible as well). -- Peter Jeremy -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 949 bytes Desc: not available URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170920/e23727ef/attachment.sig> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 6:43 ` Peter Jeremy @ 2017-09-20 8:25 ` Bakul Shah 2017-09-20 9:12 ` Steve Nickolas 0 siblings, 1 reply; 54+ messages in thread From: Bakul Shah @ 2017-09-20 8:25 UTC (permalink / raw) > On Sep 19, 2017, at 11:43 PM, Peter Jeremy <peter at rulingia.com> wrote: > > On 2017-Sep-19 18:09:27 -0700, Lyndon Nerenberg <lyndon at orthanc.ca> wrote: >> *Please* write your documentation in a way that allows you to generate >> (useful, readable!) PDF documents that I can download for offline viewing. >> Believe it or not, I don't haul along a 300 mile cat-5 cable when I go >> sailing. I still like to write code on the boat. So much for Go :-P > > One of the really nice things about Go is that all the library source code > and documentatin is installed by default and you can run a local instance of > the documentation server on your laptop (or whatever). Likewise, the > specification is one HTML page - if you really want, you could convert that > to PDF but having all the hyperlinks is really handy. (I haven't tried > running a local copy of the playground but that should be possible as well). You don't even have to install a godoc server unless you want a web interface. You can just type for example go doc regexp -- get top level regexp documentation go doc regexp/syntax -- regexp syntax go doc regexp.MustCompile -- help on just one exported function go doc regexp.Regexp -- help on exported type Regexp and a list of its methods Often this is quite handy. I just open 6 to 8 windows in acme & can have help text for various things, all accessible at once. In contrast browsers feel quite clunky. They waste a lot of white space and yet you have to scroll even on a HDMI+ rez display! ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 8:25 ` Bakul Shah @ 2017-09-20 9:12 ` Steve Nickolas 2017-09-20 9:34 ` Bakul Shah 0 siblings, 1 reply; 54+ messages in thread From: Steve Nickolas @ 2017-09-20 9:12 UTC (permalink / raw) On Wed, 20 Sep 2017, Bakul Shah wrote: > Often this is quite handy. I just open 6 to 8 windows in acme & can have > help text for various things, all accessible at once. In contrast > browsers feel quite clunky. They waste a lot of white space and yet you > have to scroll even on a HDMI+ rez display! Even links2? -uso. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 9:12 ` Steve Nickolas @ 2017-09-20 9:34 ` Bakul Shah 0 siblings, 0 replies; 54+ messages in thread From: Bakul Shah @ 2017-09-20 9:34 UTC (permalink / raw) > On Sep 20, 2017, at 2:12 AM, Steve Nickolas <usotsuki at buric.co> wrote: > > On Wed, 20 Sep 2017, Bakul Shah wrote: > >> Often this is quite handy. I just open 6 to 8 windows in acme & can have help text for various things, all accessible at once. In contrast browsers feel quite clunky. They waste a lot of white space and yet you have to scroll even on a HDMI+ rez display! > > Even links2? > > -uso. Right-click on a link in acme opens it in a browser. For help text acme works better because you can have source code in some windows, errors going to another, dir listing in another and so on. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:09 ` Lyndon Nerenberg ` (2 preceding siblings ...) 2017-09-20 6:43 ` Peter Jeremy @ 2017-09-20 16:48 ` Steffen Nurpmeso 3 siblings, 0 replies; 54+ messages in thread From: Steffen Nurpmeso @ 2017-09-20 16:48 UTC (permalink / raw) Lyndon Nerenberg <lyndon at orthanc.ca> wrote: |> On Sep 19, 2017, at 6:02 PM, Larry McVoy <lm at mcvoy.com> wrote: |> |> Put it on the web and move on. | |My main gripe about that is that I can't read the web when the router \ |I'm trying to install won't work, keeping me from the needed web documentati\ |on ... | |*Please* write your documentation in a way that allows you to generate \ |(useful, readable!) PDF documents that I can download for offline viewing. \ | Believe it or not, I don't haul along a 300 mile cat-5 cable when \ |I go sailing. I still like to write code on the boat. So much for Go :-P | |And $GOD help everyone in the Caribbean trying to bootstrap their infrastruc\ |ture right now. How is your https://... documentation going to help \ |them out? I absolutely agree. And mind "you", a lot of people save money to be able to have an hour of internet access a week. Maybe they have to walk kilometers, hours, to be able to do so. And to end up with a bad low-bandwidth connection. Having internet access is a gift, and a miracle. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt) ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:02 ` Larry McVoy 2017-09-20 1:09 ` Lyndon Nerenberg @ 2017-09-20 2:07 ` Theodore Ts'o 2017-09-24 22:58 ` Ralph Corderoy 2017-09-20 4:26 ` Grant Taylor 2 siblings, 1 reply; 54+ messages in thread From: Theodore Ts'o @ 2017-09-20 2:07 UTC (permalink / raw) On Tue, Sep 19, 2017 at 06:02:06PM -0700, Larry McVoy wrote: > > +1. Man pages should be short things that remind you how to run the program. > Putting a user guide in man pages is nuts, and in today's world texinfo is > just as nuts. Put it on the web and move on. But don't give me the see > texinfo man page, I hate that crap. Most of the core Unix utilities, even those coming from GNU, have real man pages, at least under Debian and Debian derivatives. That's because Debian makes it the package maintainer's responsibility to provide a real man page if the package doesn't have one. If you are using Debian or Ubuntu, or some other Debian derivative, and you find a man page which says, "see the texinfo/info file", you should file a bug. The other thing that often happens is that the html pages are available in /usr/share/doc/<pkg> --- but often they were generated from a texinfo file. I personally prefer to use an info file reader, as it tends to use much less battery power than a browser. So if you prefer: sensible-browser /usr/share/make/make-doc/make.html/index.html over "info make", choice is good, right? - Ted ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 2:07 ` Theodore Ts'o @ 2017-09-24 22:58 ` Ralph Corderoy 0 siblings, 0 replies; 54+ messages in thread From: Ralph Corderoy @ 2017-09-24 22:58 UTC (permalink / raw) Hi Ted, > Most of the core Unix utilities, even those coming from GNU, have real > man pages, at least under Debian and Debian derivatives. That's > because Debian makes it the package maintainer's responsibility to > provide a real man page if the package doesn't have one. That used to be a boon, but these days I've often found the Debian man page to be little more than --help output, done to close a bug against the package and worse than nothing because its existence stops anyone else having a go, including upstream as their program becomes more mature. IIRC ESR is saying RMS has agreed info format is dead and is trying to get agreement from him where to go from there, but that's been the case for a couple of years. -- Cheers, Ralph. https://plus.google.com/+RalphCorderoy ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 1:02 ` Larry McVoy 2017-09-20 1:09 ` Lyndon Nerenberg 2017-09-20 2:07 ` Theodore Ts'o @ 2017-09-20 4:26 ` Grant Taylor 2 siblings, 0 replies; 54+ messages in thread From: Grant Taylor @ 2017-09-20 4:26 UTC (permalink / raw) On 09/19/2017 07:02 PM, Larry McVoy wrote: > +1. Man pages should be short things that remind you how to run the program. > Putting a user guide in man pages is nuts, and in today's world texinfo is > just as nuts. Put it on the web and move on. But don't give me the see > texinfo man page, I hate that crap. I have long told people trying to learn unix "Most people don't learn from man pages. Man pages are great reference after you know (some of) <bla>." I typically refer someone to online tutorials or start an in person / email discussion with them about what they are trying to learn. Usually I try to tailor it to and / or reference things that I'm aware they are familiar with. -- Grant. . . . unix || die ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 0:47 ` Lyndon Nerenberg 2017-09-20 1:02 ` Larry McVoy @ 2017-09-20 16:45 ` Steffen Nurpmeso 2017-09-21 17:33 ` Tony Finch 2 siblings, 0 replies; 54+ messages in thread From: Steffen Nurpmeso @ 2017-09-20 16:45 UTC (permalink / raw) Lyndon Nerenberg <lyndon at orthanc.ca> wrote: |> On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso at mit.edu> wrote: |> |> If you take a look at how perl handles its man pages, with 188 man |> pages in section 1: | |... you quickly recognize the difference between a manpage (i.e. reference \ |page) and a user manual. Perl's (and other's) attempts to pack a 200 \ |page user guide into a block of manpages is a misuse of what manpages \ |represent. | |texinfo was a good move in the direction towards online, cross-referenced, \ |user documentation. But so often that lead to manpages that consisted \ |of the single line "see the texinfo doc"; the documentation authors \ |completely missing the point. I absolutely agree with that. It is like Hubbard laughing about "how easy anything suddenly is". I think there are different variants of letting go. ..And then many HTML versions of texinfo manuals use the split version and then you have pages with a sentence or two, which can drive you mad. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt) ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 0:47 ` Lyndon Nerenberg 2017-09-20 1:02 ` Larry McVoy 2017-09-20 16:45 ` Steffen Nurpmeso @ 2017-09-21 17:33 ` Tony Finch 2017-09-21 18:39 ` Steffen Nurpmeso 2017-09-22 3:25 ` Grant Taylor 2 siblings, 2 replies; 54+ messages in thread From: Tony Finch @ 2017-09-21 17:33 UTC (permalink / raw) Lyndon Nerenberg <lyndon at orthanc.ca> wrote: > > On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso at mit.edu> wrote: > > > > If you take a look at how perl handles its man pages, with 188 man > > pages in section 1: > > ... you quickly recognize the difference between a manpage (i.e. > reference page) and a user manual. I think it's a shame that the non-man-page parts of the Unix documentation set have been neglected, in that you don't often get newer programs following the style of the USD / SMM / PSD guides. Tony. -- f.anthony.n.finch <dot at dotat.at> http://dotat.at/ - I xn--zr8h punycode Forties: South 5 to 7, veering west 4 or 5, backing south later. Slight or moderate, occasionally rough in far northeast. Rain then fair. Poor becoming good. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-21 17:33 ` Tony Finch @ 2017-09-21 18:39 ` Steffen Nurpmeso 2017-09-22 0:02 ` Greg 'groggy' Lehey 2017-09-22 3:25 ` Grant Taylor 1 sibling, 1 reply; 54+ messages in thread From: Steffen Nurpmeso @ 2017-09-21 18:39 UTC (permalink / raw) Tony Finch <dot at dotat.at> wrote: |Lyndon Nerenberg <lyndon at orthanc.ca> wrote: |>> On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso at mit.edu> wrote: |>> |>> If you take a look at how perl handles its man pages, with 188 man |>> pages in section 1: |> |> ... you quickly recognize the difference between a manpage (i.e. |> reference page) and a user manual. | |I think it's a shame that the non-man-page parts of the Unix documentation |set have been neglected, in that you don't often get newer programs |following the style of the USD / SMM / PSD guides. The problem being that even FreeBSD dropped them from the base system. I think only NetBSD still ships with it. And Linux never had that stuff anyway, only thanks to the dedicated Linux man-pages project it is that you have anything usable at all (when not sticking with the GLibC info manual). I do not want to be back in 1999 when i desperately searched for just about anything but copyright notices in /usr/share/doc (or /usr/doc, i forgot), and that should be /usr/share/copyrights still for most of the things. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt) ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-21 18:39 ` Steffen Nurpmeso @ 2017-09-22 0:02 ` Greg 'groggy' Lehey 2017-09-22 0:30 ` Lyndon Nerenberg 2017-09-22 0:36 ` Larry McVoy 0 siblings, 2 replies; 54+ messages in thread From: Greg 'groggy' Lehey @ 2017-09-22 0:02 UTC (permalink / raw) On Thursday, 21 September 2017 at 20:39:24 +0200, Steffen Nurpmeso wrote: > Tony Finch <dot at dotat.at> wrote: > >> I think it's a shame that the non-man-page parts of the Unix >> documentation set have been neglected, in that you don't often get >> newer programs following the style of the USD / SMM / PSD guides. > > The problem being that even FreeBSD dropped them from the base > system. There was a good reason for that. To my recollection, they hadn't been maintained At All, and they were decades out of date. While they were interesting for their historical content, as user/programmer documentation they were useless at best and misleading or dangerous at worst. Greg -- Sent from my desktop computer. Finger grog at lemis.com for PGP public key. See complete headers for address and phone numbers. This message is digitally signed. If your Microsoft mail program reports problems, please read http://lemis.com/broken-MUA -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 163 bytes Desc: not available URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170922/fb99d008/attachment.sig> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:02 ` Greg 'groggy' Lehey @ 2017-09-22 0:30 ` Lyndon Nerenberg 2017-09-22 0:38 ` Larry McVoy 2017-09-22 2:20 ` Warner Losh 2017-09-22 0:36 ` Larry McVoy 1 sibling, 2 replies; 54+ messages in thread From: Lyndon Nerenberg @ 2017-09-22 0:30 UTC (permalink / raw) > On Sep 21, 2017, at 5:02 PM, Greg 'groggy' Lehey <grog at lemis.com> wrote: > > There was a good reason for that. To my recollection, they hadn't > been maintained At All, and they were decades out of date. While they > were interesting for their historical content, as user/programmer > documentation they were useless at best and misleading or dangerous at > worst. So throwing them out was easier than updating them. As I recall, the real reason they got tossed was because some factions wanted to remove the *roff tools from the base OS, meaning the viewable versions of the documents could no longer be produced. --lyndon ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:30 ` Lyndon Nerenberg @ 2017-09-22 0:38 ` Larry McVoy 2017-09-22 0:39 ` Lyndon Nerenberg 2017-09-22 3:26 ` Greg 'groggy' Lehey 2017-09-22 2:20 ` Warner Losh 1 sibling, 2 replies; 54+ messages in thread From: Larry McVoy @ 2017-09-22 0:38 UTC (permalink / raw) On Thu, Sep 21, 2017 at 05:30:50PM -0700, Lyndon Nerenberg wrote: > > > On Sep 21, 2017, at 5:02 PM, Greg 'groggy' Lehey <grog at lemis.com> wrote: > > > > There was a good reason for that. To my recollection, they hadn't > > been maintained At All, and they were decades out of date. While they > > were interesting for their historical content, as user/programmer > > documentation they were useless at best and misleading or dangerous at > > worst. > > So throwing them out was easier than updating them. > > As I recall, the real reason they got tossed was because some factions > wanted to remove the *roff tools from the base OS, meaning the viewable > versions of the documents could no longer be produced. Huh? What about the man pages? And removing roff from BSD is gonna make me mad. I'm about to start doing some work on BSD so maybe I'll make some noise. Or did the *roff tools stick around? ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:38 ` Larry McVoy @ 2017-09-22 0:39 ` Lyndon Nerenberg 2017-09-22 0:50 ` Larry McVoy 2017-09-22 3:26 ` Greg 'groggy' Lehey 1 sibling, 1 reply; 54+ messages in thread From: Lyndon Nerenberg @ 2017-09-22 0:39 UTC (permalink / raw) > On Sep 21, 2017, at 5:38 PM, Larry McVoy <lm at mcvoy.com> wrote: > > And removing roff from BSD is gonna make me mad. I'm about to start > doing some work on BSD so maybe I'll make some noise. Or did the *roff > tools stick around? Apparently they are all rewriting nroff into something called mandoc. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:39 ` Lyndon Nerenberg @ 2017-09-22 0:50 ` Larry McVoy 2017-09-22 1:01 ` Lyndon Nerenberg 2017-09-22 2:25 ` [TUHS] " Warner Losh 0 siblings, 2 replies; 54+ messages in thread From: Larry McVoy @ 2017-09-22 0:50 UTC (permalink / raw) On Thu, Sep 21, 2017 at 05:39:25PM -0700, Lyndon Nerenberg wrote: > > > On Sep 21, 2017, at 5:38 PM, Larry McVoy <lm at mcvoy.com> wrote: > > > > And removing roff from BSD is gonna make me mad. I'm about to start > > doing some work on BSD so maybe I'll make some noise. Or did the *roff > > tools stick around? > > Apparently they are all rewriting nroff into something called mandoc. Oh, brother. Like the BSD Makefile crap. "Better" but nobody else uses it. Somebody needs a clue stick. Might be them, might be me, but it's needed. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:50 ` Larry McVoy @ 2017-09-22 1:01 ` Lyndon Nerenberg 2017-09-22 1:08 ` Larry McVoy 2017-09-22 2:25 ` [TUHS] " Warner Losh 1 sibling, 1 reply; 54+ messages in thread From: Lyndon Nerenberg @ 2017-09-22 1:01 UTC (permalink / raw) On Sep 21, 2017, at 5:50 PM, Larry McVoy <lm at mcvoy.com> wrote: > > Oh, brother. Like the BSD Makefile crap. pmake, from 4.3BSD, was not evil. But the feature accretion since has been (is) insane. I really like mk. 8ed was where it first rolled out? I remember reading about it in the 10ed books. It's a joy to use in Plan 9. --lyndon ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 1:01 ` Lyndon Nerenberg @ 2017-09-22 1:08 ` Larry McVoy 2017-09-22 20:09 ` [TUHS] remaking make (Re: " Bakul Shah 0 siblings, 1 reply; 54+ messages in thread From: Larry McVoy @ 2017-09-22 1:08 UTC (permalink / raw) On Thu, Sep 21, 2017 at 06:01:49PM -0700, Lyndon Nerenberg wrote: > On Sep 21, 2017, at 5:50 PM, Larry McVoy <lm at mcvoy.com> wrote: > > > > Oh, brother. Like the BSD Makefile crap. > > pmake, from 4.3BSD, was not evil. Lots of stuff is not evil. BitKeeper, my baby, is pretty sweet. But you know what? Everyone uses Git or SVN. Being not evil isn't enough. > I really like mk. 8ed was where it first rolled out? I remember reading about it in the 10ed books. It's a joy to use in Plan 9. I like make. I carried around the source to a Sys III make (I think) because it had enough in it that it was useful and didn't have all the crud that is in GNU make. I do wish that some simple make had stuffed a scripting language in there. Anything, tcl, lua, even (horrors, can't believe I'm saying this) a little lisp. Or ideally a built in shell compat language. All those backslashes to make shell scripts work get old. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] remaking make (Re: Another "craft" discussion topic - mindless tool proliferation 2017-09-22 1:08 ` Larry McVoy @ 2017-09-22 20:09 ` Bakul Shah 0 siblings, 0 replies; 54+ messages in thread From: Bakul Shah @ 2017-09-22 20:09 UTC (permalink / raw) On Thu, 21 Sep 2017 18:08:05 -0700 Larry McVoy <lm at mcvoy.com> wrote: > > I do wish that some simple make had stuffed a scripting language in there. > Anything, tcl, lua, even (horrors, can't believe I'm saying this) a little > lisp. Or ideally a built in shell compat language. All those backslashes > to make shell scripts work get old. Google's bazel seems to have a good model and abstraction facility. For example, to build a C++ binary from {foo,main}.cc you can use cc_binary( name = "foo", srcs = ["foo.cc", "main.cc"], hdrs = ["foo.h"], ) The cc_binary macro encapsulates the common pattern for building c++ binaries, and allows you to specify just the essential (and optional) parameters. You can also define your own rules (and this is how they are adding go support). Its implementation seems to rather heavy weight (its binary installer (without jdk8) for Macs is 111MB) and there are a number of other isses so I wouldn't want to use it but it is good for mining ideas. Building something much simpler that serves the needs of most projects should be possible. May even be worth experimenting using an s-expression syntax. Then the above example becomes (cc-binary 'foo (srcs '(foo.cc main.cc)) (hdrs '(foo.h))) Shorter and much less clutter! Ideally the program should have just have meta rule built-in and everything else can be bootstrapped but it may be advantageous to "precompile" some rules.... ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:50 ` Larry McVoy 2017-09-22 1:01 ` Lyndon Nerenberg @ 2017-09-22 2:25 ` Warner Losh 1 sibling, 0 replies; 54+ messages in thread From: Warner Losh @ 2017-09-22 2:25 UTC (permalink / raw) On Thu, Sep 21, 2017 at 6:50 PM, Larry McVoy <lm at mcvoy.com> wrote: > On Thu, Sep 21, 2017 at 05:39:25PM -0700, Lyndon Nerenberg wrote: > > > > > On Sep 21, 2017, at 5:38 PM, Larry McVoy <lm at mcvoy.com> wrote: > > > > > > And removing roff from BSD is gonna make me mad. I'm about to start > > > doing some work on BSD so maybe I'll make some noise. Or did the *roff > > > tools stick around? > > > > Apparently they are all rewriting nroff into something called mandoc. > > Oh, brother. Like the BSD Makefile crap. "Better" but nobody else uses > it. > mandoc is a restricted set of troff that implements the traditional mandoc troff macros. So the conversion was just tweaking a few edge cases. And all the BSDs are using it these days. > Somebody needs a clue stick. Might be them, might be me, but it's needed > It sure beats the crazy language gnu make has become. FreeBSD has used variations on pmake the entire life of the project, though FreeBSD's version diverged somewhat until we abandoned the divergence to bring back the evolved pmake from NetBSD. Warner -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170921/2e02ffe8/attachment.html> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:38 ` Larry McVoy 2017-09-22 0:39 ` Lyndon Nerenberg @ 2017-09-22 3:26 ` Greg 'groggy' Lehey 2017-09-22 4:09 ` ron minnich 1 sibling, 1 reply; 54+ messages in thread From: Greg 'groggy' Lehey @ 2017-09-22 3:26 UTC (permalink / raw) On Thursday, 21 September 2017 at 17:38:19 -0700, Larry McVoy wrote: > On Thu, Sep 21, 2017 at 05:30:50PM -0700, Lyndon Nerenberg wrote: >> >>> On Sep 21, 2017, at 5:02 PM, Greg 'groggy' Lehey <grog at lemis.com> wrote: >>> >>> There was a good reason for that. To my recollection, they hadn't >>> been maintained At All, and they were decades out of date. While they >>> were interesting for their historical content, as user/programmer >>> documentation they were useless at best and misleading or dangerous at >>> worst. >> >> So throwing them out was easier than updating them. >> >> As I recall, the real reason they got tossed was because some factions >> wanted to remove the *roff tools from the base OS, meaning the viewable >> versions of the documents could no longer be produced. > > Huh? What about the man pages? They're still there, and are being regularly updated. > And removing roff from BSD is gonna make me mad. I'm about to start > doing some work on BSD so maybe I'll make some noise. Or did the > *roff tools stick around? roff in FreeBSD has been groff for as long as I can recall, possibly since 4.4BSD. There has been some discussion about moving it to the Ports Collection, but it's certainly not going away. Greg -- Sent from my desktop computer. Finger grog at lemis.com for PGP public key. See complete headers for address and phone numbers. This message is digitally signed. If your Microsoft mail program reports problems, please read http://lemis.com/broken-MUA -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 163 bytes Desc: not available URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170922/20bf0cfe/attachment.sig> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 3:26 ` Greg 'groggy' Lehey @ 2017-09-22 4:09 ` ron minnich 0 siblings, 0 replies; 54+ messages in thread From: ron minnich @ 2017-09-22 4:09 UTC (permalink / raw) I loved the permuted index. About once a week I'd open up the permuted index to a random location and learn something. I've never found the same joy of discovery from command line tools like apropos. On Thu, Sep 21, 2017 at 8:26 PM Greg 'groggy' Lehey <grog at lemis.com> wrote: > On Thursday, 21 September 2017 at 17:38:19 -0700, Larry McVoy wrote: > > On Thu, Sep 21, 2017 at 05:30:50PM -0700, Lyndon Nerenberg wrote: > >> > >>> On Sep 21, 2017, at 5:02 PM, Greg 'groggy' Lehey <grog at lemis.com> > wrote: > >>> > >>> There was a good reason for that. To my recollection, they hadn't > >>> been maintained At All, and they were decades out of date. While they > >>> were interesting for their historical content, as user/programmer > >>> documentation they were useless at best and misleading or dangerous at > >>> worst. > >> > >> So throwing them out was easier than updating them. > >> > >> As I recall, the real reason they got tossed was because some factions > >> wanted to remove the *roff tools from the base OS, meaning the viewable > >> versions of the documents could no longer be produced. > > > > Huh? What about the man pages? > > They're still there, and are being regularly updated. > > > And removing roff from BSD is gonna make me mad. I'm about to start > > doing some work on BSD so maybe I'll make some noise. Or did the > > *roff tools stick around? > > roff in FreeBSD has been groff for as long as I can recall, possibly > since 4.4BSD. There has been some discussion about moving it to the > Ports Collection, but it's certainly not going away. > > Greg > -- > Sent from my desktop computer. > Finger grog at lemis.com for PGP public key. > See complete headers for address and phone numbers. > This message is digitally signed. If your Microsoft mail program > reports problems, please read http://lemis.com/broken-MUA > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170922/0d48e058/attachment.html> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:30 ` Lyndon Nerenberg 2017-09-22 0:38 ` Larry McVoy @ 2017-09-22 2:20 ` Warner Losh 1 sibling, 0 replies; 54+ messages in thread From: Warner Losh @ 2017-09-22 2:20 UTC (permalink / raw) On Thu, Sep 21, 2017 at 6:30 PM, Lyndon Nerenberg <lyndon at orthanc.ca> wrote: > > > On Sep 21, 2017, at 5:02 PM, Greg 'groggy' Lehey <grog at lemis.com> wrote: > > > > There was a good reason for that. To my recollection, they hadn't > > been maintained At All, and they were decades out of date. While they > > were interesting for their historical content, as user/programmer > > documentation they were useless at best and misleading or dangerous at > > worst. > > So throwing them out was easier than updating them. > The FreeBSD handbook supplanted these docs years ago. > As I recall, the real reason they got tossed was because some factions > wanted to remove the *roff tools from the base OS, meaning the viewable > versions of the documents could no longer be produced. They were really super dated more than any other reason... Warner -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170921/48e7c5d7/attachment.html> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:02 ` Greg 'groggy' Lehey 2017-09-22 0:30 ` Lyndon Nerenberg @ 2017-09-22 0:36 ` Larry McVoy 2017-09-22 0:40 ` Lyndon Nerenberg 2017-09-22 1:53 ` Michael Parson 1 sibling, 2 replies; 54+ messages in thread From: Larry McVoy @ 2017-09-22 0:36 UTC (permalink / raw) On Fri, Sep 22, 2017 at 10:02:07AM +1000, Greg 'groggy' Lehey wrote: > On Thursday, 21 September 2017 at 20:39:24 +0200, Steffen Nurpmeso wrote: > > Tony Finch <dot at dotat.at> wrote: > > > >> I think it's a shame that the non-man-page parts of the Unix > >> documentation set have been neglected, in that you don't often get > >> newer programs following the style of the USD / SMM / PSD guides. > > > > The problem being that even FreeBSD dropped them from the base > > system. > > There was a good reason for that. To my recollection, they hadn't > been maintained At All, and they were decades out of date. While they > were interesting for their historical content, as user/programmer > documentation they were useless at best and misleading or dangerous at > worst. That's really on the maintainers, it's a shame they haven't kept those up to date. Either update them or add to them, there has to be something worth writing up. I used to *love* those manuals. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:36 ` Larry McVoy @ 2017-09-22 0:40 ` Lyndon Nerenberg 2017-09-22 1:53 ` Michael Parson 1 sibling, 0 replies; 54+ messages in thread From: Lyndon Nerenberg @ 2017-09-22 0:40 UTC (permalink / raw) > On Sep 21, 2017, at 5:36 PM, Larry McVoy <lm at mcvoy.com> wrote: > > That's really on the maintainers, it's a shame they haven't kept those > up to date. Either update them or add to them, there has to be something > worth writing up. > > I used to *love* those manuals. Plan 9's /sys/doc is refreshing. And still mostly up to date. Not because the documents haven't been updated lately, but because the OS has no need for feeping creaturism. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-22 0:36 ` Larry McVoy 2017-09-22 0:40 ` Lyndon Nerenberg @ 2017-09-22 1:53 ` Michael Parson 1 sibling, 0 replies; 54+ messages in thread From: Michael Parson @ 2017-09-22 1:53 UTC (permalink / raw) On 2017-09-21 19:36, Larry McVoy wrote: > On Fri, Sep 22, 2017 at 10:02:07AM +1000, Greg 'groggy' Lehey wrote: >> On Thursday, 21 September 2017 at 20:39:24 +0200, Steffen Nurpmeso >> wrote: >> > Tony Finch <dot at dotat.at> wrote: >> > >> >> I think it's a shame that the non-man-page parts of the Unix >> >> documentation set have been neglected, in that you don't often get >> >> newer programs following the style of the USD / SMM / PSD guides. >> > >> > The problem being that even FreeBSD dropped them from the base >> > system. >> >> There was a good reason for that. To my recollection, they hadn't >> been maintained At All, and they were decades out of date. While they >> were interesting for their historical content, as user/programmer >> documentation they were useless at best and misleading or dangerous at >> worst. > > That's really on the maintainers, it's a shame they haven't kept those > up to date. Either update them or add to them, there has to be > something > worth writing up. > > I used to *love* those manuals. I still love those manuals. The printed set of the BSD manuals were some of the first books I ordered off the Internet back in the early 1990s. Well worn, but still on my shelf. I learned a lot from them, including *roff from the URM docs. I got excited when I first installed NetBSD on my Amiga 3000 and saw that (most of) those docs were in the tree. -- Michael Parson Pflugerville, TX KF5LGQ ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-21 17:33 ` Tony Finch 2017-09-21 18:39 ` Steffen Nurpmeso @ 2017-09-22 3:25 ` Grant Taylor 1 sibling, 0 replies; 54+ messages in thread From: Grant Taylor @ 2017-09-22 3:25 UTC (permalink / raw) On 09/21/2017 11:33 AM, Tony Finch wrote: > I think it's a shame that the non-man-page parts of the Unix documentation > set have been neglected, in that you don't often get newer programs > following the style of the USD / SMM / PSD guides. In case there are other BSD n00bs, like myself, I had to look USD / SMM / PSD up. PRM - Programmer's Reference Manual PSD - Programmer's Supplementary Documents SMM - System Manager's Manual URM - User's Reference Manual USD - User's Supplementary Documents They do indeed look interesting. -- Grant. . . . unix || die ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 23:35 ` Theodore Ts'o 2017-09-20 0:47 ` Lyndon Nerenberg @ 2017-09-20 6:20 ` Lars Brinkhoff 2017-09-20 16:39 ` Steffen Nurpmeso 2017-09-24 22:54 ` Ralph Corderoy 3 siblings, 0 replies; 54+ messages in thread From: Lars Brinkhoff @ 2017-09-20 6:20 UTC (permalink / raw) Theodore Ts'o wrote: > I find that info system, with its hypertext linking, to be far more > convenient. I was somewhat amazed when I saw that the GNU info format was copied verbatim from PDP-10 INFO. The old ITS files work just fine in info today. ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 23:35 ` Theodore Ts'o 2017-09-20 0:47 ` Lyndon Nerenberg 2017-09-20 6:20 ` Lars Brinkhoff @ 2017-09-20 16:39 ` Steffen Nurpmeso 2017-09-24 22:54 ` Ralph Corderoy 3 siblings, 0 replies; 54+ messages in thread From: Steffen Nurpmeso @ 2017-09-20 16:39 UTC (permalink / raw) Theodore Ts'o <tytso at mit.edu> wrote: |On Tue, Sep 19, 2017 at 10:01:57AM -0700, Jon Steinhart wrote: |> OK, here's another one that's good for chest thumping... |> |> I am not a fan of texinfo. It doesn't provide any benefits (to me) \ |> over man. |> |> I suppose that it was trailblazing in that it broke manual pages up into |> sections that couldn't easily be viewed concurrently long before \ |> the www and |> web pages that broke things up into multiple pages to make room for \ |> more ads. | |If you take a look at how perl handles its man pages, with 188 man |pages in section 1: | |... | perlsyn Perl syntax | perldata Perl data structures | perlop Perl operators and precedence | perlsub Perl subroutines |... | |I find that info system, with its hypertext linking, to be far more |convenient. I've occasionally wished that the perl documentation was |available in info file format. To me that is a problem of the tools and the roff macros, but not of the Unix man system itself. If you look at the entire man/ual collection as a computer book, then that layout is pretty much what you get. It is mysterious -- to me -- why noone ever tried to tweak the man toolchain itself, but wrote programs like Rosetta man etc. It is nothing but a doable problem in the roff programming language and the toolchain which could have been worked around decades ago, and you have active cross references at the man(1)ual level. Instead people go an incredibly hard way and use docbook or other such solutions with an endless number of processing tools (like Jade etc.). And there is other needless bloat, NetBSD for example installs a complete set of HTML versions alongside the normal man pages, for a rather minimal benefit. But even more absurd is that in the Linux world people start using low-level roff directives to produce (inactive) blue URL links, even though GNU/Linux has the entire toolchain under control and could have done this in a regular fashion, with active URLs for at least PDF and HTML output variants. |But sometimes the extra complexity of, say, gdb or gmake, provides a |lot of convenience. And the question is whether man is a sufficient |way to provide documentation. I would humbly submit that the choice |of using man pages as used by perl is an existence proof that man is |*not* the optimal way to provide documentation for a sufficiently |complex language or program. POD is not in my opinion, especially if used with extensive cross-referencing. The problem is that today people expect references all over the place, not only at the bottom in a SEE ALSO section, and occasionally at other places. But for this you have to use a completely different way of writing the documentation than has been used traditionally on Unix. And this is not only about the people, it is about the non-existing context. Those programming IDEs that i do not use but do exist give you tooltips whenever your mouse moves over just anything, this now also on german wikipedia, for example. For this you need keywords which can be followed, to be specified in semantic context. The man macros simply do not offer that. The BSD mdoc macros extend this a bit but are hard to use and documenting C interfaces is a nightmare. I have written an extension for mdoc that gives you the possibility to specify context and the manual of the MUA i maintain, as well as the manuals of my future roff fork (but that already i think) support that. Even on the TTY, and i do not want to miss having active links in less(1), document internal as well as external, i use it all the time. Unfortunately this is restricted to very few manuals, and sometimes the chain of started less(1) instances (following .Xr external references starts a new less(1), after confirmation) gets pretty deep, and you have to quit them all in order to come back to the original manual. Well. But because the mdoc macros use a recursive parser you cannot use recursive macros, like headline macros which include a cross-reference macro, for example, and the generated reference can only be placed as a suffix because of that. And of course mdoc is a crux. Something new, implemented from scratch, with all that web-of-context in mind, something like man2, would be nice to have. Maybe it could be source compatible with man. |(If the answer is that Unix programs should never be that complicated; |that's fine. But at least for me personally, I prefer to use gdb, |with its texinfo/info files, over adb with its man page. If you want |to argue that "real programmers" should be able to decipher structure |layouts by looking at C structure declarations and creating adb macros |by hand, and that DWARF annotations are for the weak and sickly, fair |enough. :-) A good manual, which is up-to-date and refers to the actual program and not to some former version, is a key feature. It is hard to do that, and it is impossible to keep several instances at that level. Many OSS projects ship with incomplete, outdated or completely useless manuals. GNU versions often do not do anything but referring to the info manual, which likely could have been addressed decades ago by directly loading that, for example: that you read at the bottom i think. I liked to read the Plan9 manuals, these fantastic ones have really written in a way that describes the interface sufficiently, it actually enables you to start going. If that takes a few screen pages: that is just the way it is. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt) ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 23:35 ` Theodore Ts'o ` (2 preceding siblings ...) 2017-09-20 16:39 ` Steffen Nurpmeso @ 2017-09-24 22:54 ` Ralph Corderoy 2017-09-25 0:16 ` Steve Johnson 3 siblings, 1 reply; 54+ messages in thread From: Ralph Corderoy @ 2017-09-24 22:54 UTC (permalink / raw) Hi Ted, > If you take a look at how perl handles its man pages, with 188 man > pages in section 1: Yes, I went there the other day looking for something and was dismayed. The main reason being I learnt Perl thoroughly back when it was 4.something from its single perl(1) lovingly crafted by Larry Wall. Given Perl is, no was, an amalgam of Unix programming, this was perfectly possible to anyone that already new C, sh, sed, awk, grep, etc., and the man page ran smoothly, assuming all that background knowledge. Perl 5 broke this a bit with its addition of classes, and the shift to POD; still overseen by Wall. Since then, with Larry's attention elsewhere, it seems they've revelled in TMTOWTDI and the documentation has bloated so it appeared to me, looking for a reference, that there several possible man pages where it might be. Looking through those, a lot of content seem duplicated, but slightly different, and I quickly gave up. > I find that info system, with its hypertext linking, to be far more > convenient. One nice thing about info(1) in the last few years is they've ditched printing to stderr what bit of formatting they're doing, removing the need for a `Gg' in `info libc | less' to make it do that work by seeking to the end and then erase the clutter by jumping back to the beginning. > And the question is whether man is a sufficient way to provide > documentation. As others have pointed out, it wasn't the sole source of documentation; papers for bigger programs used to provide the introduction and overview leaving the man page to mop up as a reference. -- Cheers, Ralph. https://plus.google.com/+RalphCorderoy ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-24 22:54 ` Ralph Corderoy @ 2017-09-25 0:16 ` Steve Johnson 2017-09-25 11:30 ` Ralph Corderoy 0 siblings, 1 reply; 54+ messages in thread From: Steve Johnson @ 2017-09-25 0:16 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 4205 bytes --] One of the best conferences I ever attended was a Usenix conference on Little Languages, held in Santa Fe, NM. I had the pleasure of going out for dinner with a group that included Larry Wall and John Ousterhout, inventors of Perl and TCL, respectively. It was a fascinating discussion. Larry looked at Perl as if it were a natural language. Just as English has borrowed words, phrases and even syntax from other languages, Larry's view was that if it was useful and the language didn't already have it, toss it in. John came from a more mathematical (and, may I say, Unix) point of view. Small is beautiful, etc. The original motivation for TCL was to allow one process to dynamically send data to another process and get data back, so, for example, an application could send editor commands to an editor that would process them and return the result. Kind of an RPC at the process level, and, unlike pipes, the connections were dynamic. I'm not sure that ever worked in a useful way. TCL syntax was quite clean and easy to learn. But, for a lot of tasks, it seemed to take a bit more TCL to do that task than Perl did. On the other hand, when building substantial applications I personally found TCL much easier to work with -- the semantic clashes between different parts of Perl were somewhat disorienting to me. Ironically, of course, it was the TK graphics package of TCL that had real legs. System administrators found Perl to be a good vehicle for writing systems administration tools -- kind of like a shell with useful data structures. That meant that Perl was alive and well on almost every Unix-oid system out there. At the same time, writing interactive graphics applications in TK was head and shoulders easier than any other system out there, and it was very portable between systems, but it was often harder to write the application that the graphics was the interface for in TCL than in Perl. And, as I'm sure Larry would have wanted, the useful TK part migrated slowly but surely into Perl, and the rest of TCL fell into disuse. Steve ----- Original Message ----- From: "Ralph Corderoy" <ralph@inputplus.co.uk> To:"Theodore Ts'o" <tytso at mit.edu> Cc:<tuhs at minnie.tuhs.org> Sent:Sun, 24 Sep 2017 23:54:43 +0100 Subject:Re: [TUHS] Another "craft" discussion topic - mindless tool proliferation Hi Ted, > If you take a look at how perl handles its man pages, with 188 man > pages in section 1: Yes, I went there the other day looking for something and was dismayed. The main reason being I learnt Perl thoroughly back when it was 4.something from its single perl(1) lovingly crafted by Larry Wall. Given Perl is, no was, an amalgam of Unix programming, this was perfectly possible to anyone that already new C, sh, sed, awk, grep, etc., and the man page ran smoothly, assuming all that background knowledge. Perl 5 broke this a bit with its addition of classes, and the shift to POD; still overseen by Wall. Since then, with Larry's attention elsewhere, it seems they've revelled in TMTOWTDI and the documentation has bloated so it appeared to me, looking for a reference, that there several possible man pages where it might be. Looking through those, a lot of content seem duplicated, but slightly different, and I quickly gave up. > I find that info system, with its hypertext linking, to be far more > convenient. One nice thing about info(1) in the last few years is they've ditched printing to stderr what bit of formatting they're doing, removing the need for a `Gg' in `info libc | less' to make it do that work by seeking to the end and then erase the clutter by jumping back to the beginning. > And the question is whether man is a sufficient way to provide > documentation. As others have pointed out, it wasn't the sole source of documentation; papers for bigger programs used to provide the introduction and overview leaving the man page to mop up as a reference. -- Cheers, Ralph. https://plus.google.com/+RalphCorderoy -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170924/dc8d7e93/attachment-0001.html> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-25 0:16 ` Steve Johnson @ 2017-09-25 11:30 ` Ralph Corderoy 0 siblings, 0 replies; 54+ messages in thread From: Ralph Corderoy @ 2017-09-25 11:30 UTC (permalink / raw) Hi Steve, The need for speed was prevalent back around the time of Perl and Tcl's creation. We could get the work done with sh and awk, but the overhead of new processes, and moving data between them lots of times, was a problem for larger workloads. > Larry's view was that if it was useful and the language didn't already > have it, toss it in. Perl placed the best ideas of sed and awk inline in the language, and Larry's implementation put a lot of effort into speed; the bytecode interpreter, the regexp engine, the hash table, ... The cumulative effect was very noticeable. Larry's tossing was quite skilled. For example, the regexp syntax took all those previous flavours and gave them some consistency: meta-characters were punctuation and backslashes escaped them whereas backslashed letters allowed new things like the \d and \s conveniences. If he hadn't been a dab hand, well, there lies PHP and its real_kitchen_sink2(). I read Ousterhout's papers on Tcl and Tk, and tried using Tcl for a while. The `everything is a string' became wearing, and the performance wasn't there for large amounts of data. Perhaps because it was considered a glue and you'd link it it with C for the hard bits, but that was a bit too much effort for scripting that often starts with something intended to be thrown away. Yes, Tk's nice, and its Canvas widget with vector objects stood out against the Athena, Motif, etc., available at the time. The IDs and tags were very useful. Change an attribute of all things with tag T and it took care of the redraw. I used it for a digital-circuit simulation once. -- Cheers, Ralph. https://plus.google.com/+RalphCorderoy ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-19 17:01 [TUHS] Another "craft" discussion topic - mindless tool proliferation Jon Steinhart 2017-09-19 17:05 ` Steve Nickolas 2017-09-19 23:35 ` Theodore Ts'o @ 2017-09-20 18:15 ` Clem Cole 2017-09-20 18:35 ` Jon Steinhart 2 siblings, 1 reply; 54+ messages in thread From: Clem Cole @ 2017-09-20 18:15 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 2874 bytes --] I fear this thread drifted from Jon's point about improving a tool, instead of replacing it. On Tue, Sep 19, 2017 at 1:01 PM, Jon Steinhart <jon at fourwinds.com> wrote: > OK, here's another one that's good for chest thumping... > > I am not a fan of texinfo. It doesn't provide any benefits (to me) over > man. > Amen... To me this was just rms trying to inflict ITS/emacs on Unix. Lars points out info is just ITS format, the tool is just emacs commands. The key was that here was a case where the UNIX solution (man) was perfectly reasonable, worked very well. But it was not the likely and in the right flavor of rms. > This is a systemic problem. I have a section in my book-in-progress where > I > talk about being a "good programming citizen". One of the things that I > say > is: > > Often there is a tool that does most of what you need but is lacking > some feature or other. Add that feature to the existing tool; > don't just write a new one. The problem with writing a new one > is that, as a tool user, you end up having to learn a lot of tools > that perform essentially the same function. It's a waste of time > an energy. A good example is the make utility (invented by Stuart > Feldman at Bell Labs in 1976) that is used to build large software > packages. As time went on, new features were needed. Some were > added to make, but many other incompatible utilities were created that > performed similar functions. Don't create burdens for others. > Improve existing tools if possible. Which is exactly your point. I think you are spot on here. Instead of rms trying to learn to use Unix the way, he inflicted the ITS/emacs way because he thought it was ``better.'' Which is a tad arrogant. I have noted that the folks that don't mind and/or like info, are regular emacs users. Someone like me, who can use emacs, but does not find it the only thing (I could switch between RPN - HP style and algebraic - TI calculators too), just find texinfo to be an annoyance. It's different and one extra place to look. As Jon said, it does not provide any benefits and in fact is a detraction because it means the standard Unix tools like apropros does not index it. Larry has right idea, with his webroff. Make html when it is appropriate I also think, man pages are man pages and not user manuals. The Perl example was classic. We did not learn C from the man page. What we got in the C man page was how to run it. There was a manual (doc) for the language. That should have been a manual (in -ms macros) and then run through Larry's webroff and properly indexed. Then you get everything. Clem -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170920/c61c9434/attachment.html> ^ permalink raw reply [flat|nested] 54+ messages in thread
* [TUHS] Another "craft" discussion topic - mindless tool proliferation 2017-09-20 18:15 ` Clem Cole @ 2017-09-20 18:35 ` Jon Steinhart 0 siblings, 0 replies; 54+ messages in thread From: Jon Steinhart @ 2017-09-20 18:35 UTC (permalink / raw) Another point that has been hinted at on the man page discussion. A concept that seemed to get lost at the FSF is that man pages are summaries. They're not exhaustive. While a man page is all that's needed for something simple like "ls", I expect there to be well written documents for more complex programs. For example, I do not expect a complete description of yacc on the man page; that belongs in a separate document. I still have notebooks with the printed versions of the old docs around. The man page problem is also exacerbated by the bloatage that afflicts the FSF versions of many formerly simple utilities. Huge numbers of dash options plague many utilities that in my opinion should be broken up into separate simpler programs. Not to mention that by adding so many options they felt the need for long options, and now one has to deal with two options for some but not all things. Making things worse, some man pages are just not written with the user in mind. The one that constantly annoys me is bash. There's around 450 lines of gunk about shell variables near the front which I always have to skip past because I forgot the syntax of some parameter expansion. I hardly ever care about the shell variables, and I don't think that I'm alone. Jon ^ permalink raw reply [flat|nested] 54+ messages in thread
end of thread, other threads:[~2017-09-25 11:30 UTC | newest] Thread overview: 54+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-09-19 17:01 [TUHS] Another "craft" discussion topic - mindless tool proliferation Jon Steinhart 2017-09-19 17:05 ` Steve Nickolas 2017-09-19 20:31 ` Pete Turnbull 2017-09-19 20:37 ` Warner Losh 2017-09-19 23:35 ` Theodore Ts'o 2017-09-20 0:47 ` Lyndon Nerenberg 2017-09-20 1:02 ` Larry McVoy 2017-09-20 1:09 ` Lyndon Nerenberg 2017-09-20 1:13 ` Larry McVoy 2017-09-20 1:22 ` Larry McVoy 2017-09-20 2:01 ` Larry McVoy 2017-09-20 2:34 ` Bakul Shah 2017-09-20 2:47 ` Larry McVoy 2017-09-20 6:18 ` Bakul Shah 2017-09-20 4:35 ` Grant Taylor 2017-09-20 5:54 ` Ian Zimmerman 2017-09-24 23:03 ` Ralph Corderoy 2017-09-24 23:35 ` Bakul Shah 2017-09-20 16:49 ` Steffen Nurpmeso 2017-09-20 4:29 ` Grant Taylor 2017-09-20 6:43 ` Peter Jeremy 2017-09-20 8:25 ` Bakul Shah 2017-09-20 9:12 ` Steve Nickolas 2017-09-20 9:34 ` Bakul Shah 2017-09-20 16:48 ` Steffen Nurpmeso 2017-09-20 2:07 ` Theodore Ts'o 2017-09-24 22:58 ` Ralph Corderoy 2017-09-20 4:26 ` Grant Taylor 2017-09-20 16:45 ` Steffen Nurpmeso 2017-09-21 17:33 ` Tony Finch 2017-09-21 18:39 ` Steffen Nurpmeso 2017-09-22 0:02 ` Greg 'groggy' Lehey 2017-09-22 0:30 ` Lyndon Nerenberg 2017-09-22 0:38 ` Larry McVoy 2017-09-22 0:39 ` Lyndon Nerenberg 2017-09-22 0:50 ` Larry McVoy 2017-09-22 1:01 ` Lyndon Nerenberg 2017-09-22 1:08 ` Larry McVoy 2017-09-22 20:09 ` [TUHS] remaking make (Re: " Bakul Shah 2017-09-22 2:25 ` [TUHS] " Warner Losh 2017-09-22 3:26 ` Greg 'groggy' Lehey 2017-09-22 4:09 ` ron minnich 2017-09-22 2:20 ` Warner Losh 2017-09-22 0:36 ` Larry McVoy 2017-09-22 0:40 ` Lyndon Nerenberg 2017-09-22 1:53 ` Michael Parson 2017-09-22 3:25 ` Grant Taylor 2017-09-20 6:20 ` Lars Brinkhoff 2017-09-20 16:39 ` Steffen Nurpmeso 2017-09-24 22:54 ` Ralph Corderoy 2017-09-25 0:16 ` Steve Johnson 2017-09-25 11:30 ` Ralph Corderoy 2017-09-20 18:15 ` Clem Cole 2017-09-20 18:35 ` Jon Steinhart
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).