Prev: Delete Chinese characters from the filenames.
Next: Remove certain characters in a filename
From: Seebs on 2 Feb 2010 00:00
On 2010-02-02, Ivan Shmakov <ivan(a)main.uusia.org> wrote:
> Personally, I'd rather recommend having a hard copy of the
> Texinfo manual in question first, to read in one's spare time.

I last printed manuals in the early 90s. I want something I can
search.

> Otherwise, it's rather ?check the (info) manual for the package
> you're using; check for any manual pages if there's none? in my
> version of the universe.

Except in the degenerate case where the man page sucks, I have never seen
a case where the info page was as useful for "I forgot the command line
usage" as the man page was.

> S> True. But it was intended, reasonably, as an improvement over man
> S> pages. Just one problem: It simply isn't enough of an improvement
> S> to justify the breakage.

> ... Even when it comes to making a hard copy?

Honestly, yes. I've got printed out man pages from way back when, and
frankly, info isn't much better.

> Well, let me think... I use Emacs when it's justified to ?boot?
> one on a host. I also use Vim and, occasionally, Ed. Surely, I
> use Awk, Tcl and Sed, both from Shell and from Emacs. Does it
> count as ?nothing else for anything??

Well, in my case, I've never trained my fingers for the emacs commands,
making the info program annoying useless.

> S> An index on a whole bunch of separate documents is often less useful
> S> than a single all-in-one searchable text document. The people doing
> S> the indexes may not have categorized something the way I would have;
> S> a plain search is often faster.

> The index, as included into almost every Info document, allows
> for a quick access to the documentation for the particular
> system or language functions, commands, etc. Instead of having
> a Man section to specify a ?namespace?, one specifies the
> namespace to search in by choosing a particular Info document.

And if I know what section I want, then that's useful, otherwise, it's
anti-useful, because a single document all of which I can search with
a single search command is more useful to me.

> And now, I'm not completely sure that $ man would allow me to
> distinguish at least three different printf functions in its 3rd
> section.

They wouldn't all be in the third section. If I want to know about the
printf in awk, it's in man awk. Otherwise, "man 3 printf" and "man 1 printf"
seem to work pretty well.

> Does it mean that Info already existed when you were introduced
> to Unix or GNU?

Yes. So did the GNU indentation standard. That it already existed doesn't
mean it was a good idea, or should ever have come into existence.

> S> Having a command "foo" for which "man foo" does not produce full
> S> documentation of the usage and invocation of the command is a bad
> S> choice.

> Why?

Principle of least astonishment.

As long as a large number of packages have man pages, and man pages are
somewhat standardized and apply across multiple enviroments, keeping them
working is probably right.

> Having $ foo --help for basic usage seems to me quite
> enough. Therefore, I'd better drop the Man pages entirely for
> the sake of simplicity. (The only of my packages that includes
> Man pages does this because I had no time to prepare a proper
> manual.)

If you can only do one, do man pages first, because that's the standard
tool.

> S> It's like the GNU coding standards.

> What I like of the GNU coding standards is that they're a
> well-documented practice.

It's well-documented, and FANTASTICALLY, UTTERLY, STUPID.

As Linus Torvalds put it: The first thing you should do is print out
a copy of the GNU coding standards, and burn them.

They're bad at every level; the technical advice has historically been
awful, the stylistic advice is awful, and the indentation style is a
brand new style which serves no purpose other than to be completely
different from all the previously-extant indentation styles.

> Sometimes, I advice people to follow
> the GNU standards just because ?sure, you could invent your own
> standards, but why bother? and you're much likely to forget what
> you've invented by the time the work is done, anyway!?

Which is a great argument for using *a* standard, but the GNU standards
are by far the worst I've ever seen published. (Actually, that's not
quite true; I believe MS did at one point publish a recommendation for
their bastardized "Hungarian", and that was actually as bad.)

> Still, I was, and continue to be, very impressed by the sheer
> volume of work done by the GNU folks.

So what? The info system is still stupid. It was a bad idea, poorly
implemented, and it hasn't gotten better.

> And I owe them much,
> because I wouldn't have been a 1% of the programmer I'm now
> without the GNU project and, specifically, its documentation.

If you owe an engineer something, the best thing to pay back is honest
criticism of his mistakes.

> And, at times, an inferior, but well-documented practice is
> better than a superior, but poorly-documented one.

At some times, but in both the info and coding standards cases, the existing
practices were better documented and technically superior.

It's great that they've made some useful stuff available, but it doesn't
make the bad things somehow not-bad.

-s
--
Copyright 2010, all wrongs reversed. Peter Seebach / usenet-nospam(a)seebs.net
http://www.seebs.net/log/ <-- lawsuits, religion, and funny pictures
http://en.wikipedia.org/wiki/Fair_Game_(Scientology) <-- get educated!
From: Chris F.A. Johnson on 2 Feb 2010 03:29
On 2010-02-01, Ivan Shmakov wrote:
>
>>>>>> "S" == Seebs <usenet-nospam(a)seebs.net> writes:
>>>>>> "IS" == Ivan Shmakov <ivan(a)main.uusia.org> wrote:
>
> IS> The documentation for the GNU project's tools is maintained in the
> IS> Texinfo format.
>
> S> Which violates the principle of least surprise to an astonishing
> S> extent.
>
> ... What really surprises me is the special handling of ! by the
> interactive Bash instances.

Why bother with it? I set histchars to the empty string and the
exclamation mark is a normal character, as it should be.


--
Chris F.A. Johnson, author <http://shell.cfajohnson.com/>
===================================================================
Shell Scripting Recipes: A Problem-Solution Approach (2005, Apress)
Pro Bash Programming: Scripting the GNU/Linux Shell (2009, Apress)
===== My code in this post, if any, assumes the POSIX locale =====
===== and is released under the GNU General Public Licence =====
First  |  Prev  | 
Pages: 1 2 3
Prev: Delete Chinese characters from the filenames.
Next: Remove certain characters in a filename