[TUHS] Another "craft" discussion topic - mindless tool proliferation

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Jon Steinhart]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steve Nickolas]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Pete Turnbull]

[-- 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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Warner Losh]

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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Theodore Ts'o]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lyndon Nerenberg]

> 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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lyndon Nerenberg]

> 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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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 

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Theodore Ts'o]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Bakul Shah]

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 

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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 

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Grant Taylor]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Grant Taylor]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Grant Taylor]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Ian Zimmerman]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Bakul Shah]

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 

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lars Brinkhoff]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Peter Jeremy]

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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Bakul Shah]

> 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!

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steve Nickolas]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Bakul Shah]

> 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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steffen Nurpmeso]

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)

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steffen Nurpmeso]

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)

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steffen Nurpmeso]

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)

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steffen Nurpmeso]

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)

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Clem Cole]

[-- 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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Jon Steinhart]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Tony Finch]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steffen Nurpmeso]

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)

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Greg 'groggy' Lehey]

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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lyndon Nerenberg]

> 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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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?

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lyndon Nerenberg]

> 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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lyndon Nerenberg]

> 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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Lyndon Nerenberg]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Larry McVoy]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Michael Parson]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Warner Losh]

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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Warner Losh]

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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Grant Taylor]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Greg 'groggy' Lehey]

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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[ron minnich]

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>

[TUHS] remaking make (Re: Another "craft" discussion topic - mindless tool proliferation

[Bakul Shah]

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....

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Ralph Corderoy]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Ralph Corderoy]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Ralph Corderoy]

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

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Bakul Shah]

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.

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Steve Johnson]

[-- 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>

[TUHS] Another "craft" discussion topic - mindless tool proliferation

[Ralph Corderoy]

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