19 Sep
2017
19 Sep
'17
11:01 p.m.
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
19 Sep
19 Sep
11:05 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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.
20 Sep
20 Sep
2:31 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On 19/09/2017 18:05, Steve Nickolas wrote:
On Tue, 19 Sep 2017, Jon Steinhart wrote:
LOL! Yes, I come across that attitude all too often. I must remember
that phrase :-)
--
Pete
Pete Turnbull
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". 
2:37 a.m.
On Tue, Sep 19, 2017 at 2:31 PM, Pete Turnbull <pete(a)dunnington.plus.com>
wrote:
On 19/09/2017 18:05, Steve Nickolas wrote:
Don't you mean "Blinded by the 1337?" or is 1337-speak passed from cool
into pase' now?
Warner
On Tue, 19 Sep 2017, Jon Steinhart wrote:
Turns out that one of the main reasons given for angular over jQuery was
LOL! Yes, I come across that attitude all too often. I must remember
that phrase :- 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".
5:35 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
6:47 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 19, 2017, at 4:35 PM, Theodore Ts'o
<tytso(a)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
7:02 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Tue, Sep 19, 2017 at 05:47:42PM -0700, Lyndon Nerenberg 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.
On Sep 19, 2017, at 4:35 PM, Theodore Ts'o
<tytso(a)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.
7:09 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 19, 2017, at 6:02 PM, Larry McVoy
<lm(a)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
7:13 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Tue, Sep 19, 2017 at 06:09:27PM -0700, Lyndon Nerenberg wrote:
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.
On Sep 19, 2017, at 6:02 PM, Larry McVoy
<lm(a)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?
7:22 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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:
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
On Sep 19, 2017, at 6:02 PM, Larry McVoy
<lm(a)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?
8:01 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
8:34 a.m.
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(a)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
8:47 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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(a)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
12:18 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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(a)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(a)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 
10:35 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
11:54 a.m.
On 2017-09-19 22:35, Grant Taylor wrote:
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.
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?) 
25 Sep
25 Sep
5:03 a.m.
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
5:35 a.m.
On Mon, 25 Sep 2017 00:03:08 +0100 Ralph Corderoy <ralph(a)inputplus.co.uk> wrote:
Ralph Corderoy writes:
Bakul Shah wrote:
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.
These days I use the markdown format more and
more
http://undeadly.org/cgi?action=article&sid=20170304230520
has some reasons to dislike Markdown. :-) 
20 Sep
20 Sep
10:49 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
Larry McVoy <lm(a)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(a)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)
10:29 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
12:43 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On 2017-Sep-19 18:09:27 -0700, Lyndon Nerenberg <lyndon(a)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
2:25 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 19, 2017, at 11:43 PM, Peter Jeremy
<peter(a)rulingia.com> wrote:
On 2017-Sep-19 18:09:27 -0700, Lyndon Nerenberg <lyndon(a)orthanc.ca> wrote:
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!
*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).
3:12 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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.
3:34 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 20, 2017, at 2:12 AM, Steve Nickolas
<usotsuki(a)buric.co> wrote:
On Wed, 20 Sep 2017, Bakul Shah wrote:
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.
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.
10:48 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
Lyndon Nerenberg <lyndon(a)orthanc.ca> wrote:
|> On Sep 19, 2017, at 6:02 PM, Larry McVoy <lm(a)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)
8:07 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
25 Sep
25 Sep
4:58 a.m.
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
20 Sep
20 Sep
10:26 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
10:45 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
Lyndon Nerenberg <lyndon(a)orthanc.ca> wrote:
|> On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso(a)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)
21 Sep
21 Sep
11:33 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
Lyndon Nerenberg <lyndon(a)orthanc.ca> 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.
Tony.
--
f.anthony.n.finch <dot(a)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.
On Sep 19,
2017, at 4:35 PM, Theodore Ts'o <tytso(a)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.
22 Sep
22 Sep
12:39 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
Tony Finch <dot(a)dotat.at> wrote:
|Lyndon Nerenberg <lyndon(a)orthanc.ca> wrote:
|>> On Sep 19, 2017, at 4:35 PM, Theodore Ts'o <tytso(a)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)
6:02 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Thursday, 21 September 2017 at 20:39:24 +0200, Steffen Nurpmeso wrote:
Tony Finch <dot(a)dotat.at> 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.
Greg
--
Sent from my desktop computer.
Finger grog(a)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
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.
6:30 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 21, 2017, at 5:02 PM, Greg 'groggy'
Lehey <grog(a)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
6:38 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Thu, Sep 21, 2017 at 05:30:50PM -0700, Lyndon Nerenberg wrote:
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?
On Sep 21, 2017, at 5:02 PM, Greg
'groggy' Lehey <grog(a)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.
6:39 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 21, 2017, at 5:38 PM, Larry McVoy
<lm(a)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.
6:50 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Thu, Sep 21, 2017 at 05:39:25PM -0700, Lyndon Nerenberg wrote:
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.
On Sep 21, 2017, at 5:38 PM, Larry McVoy
<lm(a)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.
7:01 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 21, 2017, at 5:50 PM, Larry McVoy <lm(a)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
7:08 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Thu, Sep 21, 2017 at 06:01:49PM -0700, Lyndon Nerenberg wrote:
On Sep 21, 2017, at 5:50 PM, Larry McVoy
<lm(a)mcvoy.com> wrote:
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.
Oh, brother. Like the BSD Makefile crap.
pmake, from 4.3BSD, was not evil. 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.
23 Sep
23 Sep
2:09 a.m.
New subject: remaking make (Re: Another "craft" discussion topic - mindless tool proliferation
On Thu, 21 Sep 2017 18:08:05 -0700 Larry McVoy <lm(a)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....
22 Sep
22 Sep
8:25 a.m.
On Thu, Sep 21, 2017 at 6:50 PM, Larry McVoy <lm(a)mcvoy.com> wrote:
On Thu, Sep 21, 2017 at 05:39:25PM -0700, Lyndon
Nerenberg wrote:
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.
On Sep 21, 2017, at 5:38 PM, Larry McVoy
<lm(a)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. 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
8:20 a.m.
On Thu, Sep 21, 2017 at 6:30 PM, Lyndon Nerenberg <lyndon(a)orthanc.ca> wrote:
The FreeBSD handbook supplanted these docs years ago.
On Sep 21, 2017, at 5:02 PM, Greg
'groggy' Lehey <grog(a)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.
They were really super dated more than any other reason...
Warner
6:36 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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:
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.
Tony Finch <dot(a)dotat.at> 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. 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.
6:40 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
On Sep 21, 2017, at 5:36 PM, Larry McVoy
<lm(a)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.
7:53 a.m.
On 2017-09-21 19:36, Larry McVoy wrote:
On Fri, Sep 22, 2017 at 10:02:07AM +1000, Greg
'groggy' Lehey wrote:
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
On Thursday, 21 September 2017 at 20:39:24 +0200,
Steffen Nurpmeso
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. Tony Finch <dot(a)dotat.at> 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. 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.
9:26 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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:
Huh? What about the man pages?
They're still there, and are being regularly updated.
On Sep 21, 2017, at 5:02 PM, Greg
'groggy' Lehey <grog(a)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. 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(a)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
10:09 a.m.
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(a)lemis.com>
wrote:
On Thursday, 21 September 2017 at 17:38:19 -0700,
Larry McVoy wrote:
Huh? What about the man pages?
They're still there, and are being regularly updated.
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(a)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. 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(a)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
9:25 a.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
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
10:39 p.m.
New subject: Another "craft" discussion topic - mindless tool proliferation
Theodore Ts'o <tytso(a)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)
25 Sep
25 Sep
4:54 a.m.
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
6:16 a.m.
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(a)inputplus.co.uk>
To:"Theodore Ts'o" <tytso(a)mit.edu>
Cc:<tuhs@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
5:30 p.m.
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
21 Sep
21 Sep
12:15 a.m.
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(a)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
12:35 a.m.
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
2645
days inactive
2651
days old
53 comments
20 participants
participants (20)
-
Bakul Shah -
Clem Cole -
Grant Taylor -
Greg 'groggy' Lehey -
Ian Zimmerman -
Jon Steinhart -
Larry McVoy -
Lars Brinkhoff -
Lyndon Nerenberg -
Michael Parson -
Pete Turnbull -
Peter Jeremy -
Ralph Corderoy -
ron minnich -
Steffen Nurpmeso -
Steve Johnson -
Steve Nickolas -
Theodore Ts'o -
Tony Finch -
Warner Losh