Subject: Two New Software-Related Ideas

From: Shlomi Fish <[email-masked]>
Date: Tue, 19 Sep 2006 10:10:54 +0300

Hi all!

You can find two new software-related ideas that I scribbled down here:

* http://www.shlomifish.org/philosophy/ideas/#tucan

* http://www.shlomifish.org/philosophy/ideas/unixdoc/

Please let me know what you think.

Regards,

	Shlomi Fish

---------------------------------------------------------------------
Shlomi Fish      [email-masked]
Homepage:        http://www.shlomifish.org/

Chuck Norris wrote a complete Perl 6 implementation in a day but then
destroyed all evidence with his bare hands, so no one will know his secrets.

---

From: "Nadav Har'El" <[email-masked]>
Date: Tue, 19 Sep 2006 13:16:38 +0300

> * http://www.shlomifish.org/philosophy/ideas/unixdoc/

Once upon a time (about a decade ago), I used "tkman" to read manual pages.
It was similar to what you were looking for - a graphical, hypertext manual
page (and now I see, also texinfo) browser. It added links between pages
(so you could click on those "see also" sections or mentions of cat(1)),
and was much more "cool" than using "man" in a text terminal.

-- 
Nadav Har'El                        |       Tuesday, Sep 19 2006, 26 Elul 5766
[email-masked]             |-----------------------------------------
Phone +972-523-790466, ICQ 13349191 |Why do programmers mix up Christmas and
http://nadav.harel.org.il           |Halloween? Because DEC 25 = OCT 31

---

From: Shlomi Fish <[email-masked]>
Date: Fri, 22 Sep 2006 19:19:08 +0300

> and was much more "cool" than using "man" in a text terminal.

I see. Nevertheless, I need such a thing also for other formats, and with 
other features. And naturally, there should be a terminal front-end.

Regards,

	Shlomi Fish

---

From: "Beni Cherniavsky" <[email-masked]>
Date: Fri, 22 Sep 2006 01:03:44 +0300

> and was much more "cool" than using "man" in a text terminal.
I think the common format fed to presentation engines should be HTML
(perhaps adding some microformats to add semantics).  It satisfies all
your goals, with more tools around it than any other format.  links
does a decent job of showing HTML at the terminal.

Existing {texi,info,man}2html converters are a bit lame from the
output aesthetics perspective.  Nevertheless, 'dwww' (debian only I
think) does a very nice job of integrating them into a uniform
browsing experience.

-- 
Beni Cherniavsky <[email-masked]>, who can only read email on weekends.

---

From: Omer Zak <[email-masked]>
Date: Mon, 02 Oct 2006 19:51:15 +0200

One thing whose absence I sorely feel:
An improved way to have apropos.

I often need to accomplish a task, remember that there is some command
which can be used to accomplish this task.  But do not remember which
command - not because I was lazy, did not RTFM, or whatever - but
because my need to perform this specific task is rare enough for me not
to remember how to accomplish it.

It would be nice to have some sort of database or a search engine, into
which you can type keywords describing the task and it displays to you a
list of potentially relevant software tools, command line options and
commands which might be relevant to performance of that task.

                                        --- Omer

-- 
You haven't made an impact on the world before you caused a Debian
release to be named after Snufkin.
My own blog is at http://tddpirate.livejournal.com/

My opinions, as expressed in this E-mail message, are mine alone.
They do not represent the official policy of any organization with which
I may be affiliated in any way.
WARNING TO SPAMMERS:  at http://www.zak.co.il/spamwarning.html

---

From: "Beni Cherniavsky" <[email-masked]>
Date: Mon, 2 Oct 2006 21:33:54 +0200

> An improved way to have apropos.
[...]
> commands which might be relevant to performance of that task.
On debian, I frequently use "apt-cache search".  When I don't know how to
formulate the search I launch "synaptic" and try all the searches I
can think of.
Both search the full description texts of all packages, which gives better
results than man -k.  Also, if I'm looking for the right tool, I want
to consider
all availiable packages, not only those those that happen to be installed.

On other distributions, I expect that searching the package database will
also give good results.

-- 
Beni Cherniavsky <[email-masked]>

---

From: "Amit Aronovitch" <[email-masked]>
Date: Wed, 25 Oct 2006 01:19:03 +0200

This is a repost of my message from 21/9
(I was told it was rejected and I have to repost)

comments relate to the "unixdoc" idea.

rants--well, guess I was in a cynical mood that day.

------------------------------------------------------------------------------------------
From: Amit Aronovitch <[email-masked]>	Mailed-By: gmail.com
To: [email-masked]
Date: Sep 21, 2006 1:42 AM
Subject: Re: [hackers-il] Two New Software-Related Ideas

(a)

http://www.gnu.org/software/texinfo/

You all probably know that, but shame it is not mentioned - not even
as an input format.

Few facts (I know a few people which I was very surprised to find out
they did not even know that info exists):

1) All the detailed/updated documentation of all GNU components come
as info. man pages are either a brief summary or inserted by the
distros) - try "info bash", "info find", "info coreutils" on any GNU
based system (in fact all propriatary unices I happened to work on in
the last 5 years offer a provider-prepared compilation of standard gnu
tools - info included)

 (Better to avoid using man on GNU tools - in many cases important
information was dropped out. Plus - once you get used to the interface
- navigation and searching is much more flexible - even for reading
plain manpages)

2) The texinfo system is menu driven and hyperlinked. It supports
generating a pretty hardcopy (using tex) and html.

3) The major problem is that the standard browser (info info -
contains a tutorial), is very emacs-ish, which, while immediate and
intuitive to some of us, is intimidating to others. Also it's not new
- therefore not "cool" (people seem to think that anything that was
invented earlier than last year is old-fashioned and can't be any
good).
 However: nothing prevents you for writing graphical viewers. In fact,

4) Modern desktop systems already provide interface to the info system
(in Gnome yelp, you find the info directory under "command line help"
next to the man pages).

---------------------------

(b)

Debian provides a nice set of tools, which should let you read all
docs (man, info and html-docs) of installed packages using your web
browser ( I think most packages do register themself using doc-base) .
 I believe the 3 alternatives are "dwww","doc-central" and "dhelp"
(each having different set of capabilities and different requirements
- e.g. dhelp does not require a webserver)
 This is all I can say right now - since I did not yet try any of the 3.

----------------------------

(c)

 Some rants about "modern style" of documentation (Gnome/KDE docbooks) :
The modern desktops seem to think that their form of docs is so much
better than the "old fashioned" man/info, that they don't bother
providing any other form, even for commandline tools. It seems that
even Debian packagers (which are usually very strict about having
manpages)  fall to that dogma.

 However, the documentation that does exist in their fancy graphical
system (which of course very *cool* and *modern*), is close to 100%
what I call "useless menu listing"(*) - all the trivial parts that you
can easily find out yourself are documented, but anything useful
enough you'd bother opening the help for is considered "expert-level
details" that would only confuse and bother the poor stupid^H Eh...
sorry... *respected* user in Joelspeak (
http://www.joelonsoftware.com/uibook/chapters/fog0000000062.html ).
 I say - if you really think "users" (FTR, I resent the term) don't
read the manual (obviously false generalization), don't document at
all (see if you can get you clients to accept "users don't read" as an
excuse for that...). If  you bother to document - document the
*important* stuff. If I clicked "help" I probably *do* want to get
some info - right?

 AA

 (*) Go to the nearest book-shop and pick some random computer book,
say a (fictitional) 600 pages "F. Mbogo's Absolute Guide to Microsoft
Word", open some random page.
Most probably you'll see something like this:
...
1.2.3 The File menu:
1.2.3.1 The "New" command
  Use this to start working on a new document. A menu pops up asking
you to choose the type of document - see figure 1.16.
1.2.3.2 The "Open" command
 To open a new file select this option. A window will pop up,
allowing you to pick the file you want to edit (see figure 1.17).
Detailed description on using that window can be found in  F. Mbogo's
"Power User's Guide to Windows Explorer"
...

---

From: Shlomi Fish <[email-masked]>
Date: Wed, 25 Oct 2006 18:24:27 +0200

On Wednesday 25 October 2006 01:19, Amit Aronovitch wrote:
> ---------------------------------------------------------------------------
>--------------- From: Amit Aronovitch <[email-masked]>	Mailed-By:
> gmail.com

Yes, I'm aware of GNU texinfo. I don't remember why I didn't include it. 
Perhaps it was out of due frustration from its limitations or the fact that I 
found the "info" reader to be so counter-intuitive.

I normally use the HTML documentation (as converted from the texinfo sources) 
at gnu.org.

> - navigation and searching is much more flexible - even for reading

One problem Nadav once mentioned with the info pages, is that they are split 
into several sections and sub-sections and so one cannot search them for a 
keyword as conveniently as one can using a man page.

> generating a pretty hardcopy (using tex) and html.

Yes, albeit its support for hypertext is relatively limited in comparison to 
DocBook.

> intuitive to some of us, is intimidating to others. 

I could never get the hang of the "info" command line. :-)

> Also it's not new 

Yes.

Interesting. I suppose it uses texinfo2html and man2html. Not precisely the 
level of integration that I'm looking for.

You're right about that. Of course, I often end up consulting the code for how 
to do something using a program.

Regards,

	Shlomi Fish

--

---

From: "Amit Aronovitch" <[email-masked]>
Date: Thu, 26 Oct 2006 11:20:21 +0200

> found the "info" reader to be so counter-intuitive.

Driven away because of the frontend... exactly as I said in (3).
info is only intuitive to Emacsers, and most of them read the info
with the emacs frontend anyway.
 I wonder if there's a "viper"-like keyboard scheme for info, or a
standalone vi-like reader. These might do wonders to the popularity of
the system.

 Anyways, if you consider writing a new doc framework - supporting
info as input source would greatly increase the amount of docs
available to your system (the useful ones, at least ;-)).

> I normally use the HTML documentation (as converted from the texinfo sources)

That's remote documentation - not available when your'e offline, and
may not match the versions you have installed on your machine (that
is, unless your distro takes care of installing these htmls locally in
a centralized way - e.g. dhelp and friends)

 Maybe it would be better to use your desktop's help system - I think
both KDE and Gnome help are aware of the installed info docs and allow
you to browse and read them.

> keyword as conveniently as one can using a man page.

I was told that too.
But this is FALSE (maybe it was true in old versions - I don't know).

Both normal search (s, prompts for input, like '/' in man) and the
electric-search (^s, search-as-you-type, like '/' in firefox) work
across sections (they view the whole topic as if it was one big
document).
 btw, in the Emacs frontend, electric search is page-local, which is,
in fact, one of the reasons I prefer the standalone info reader.

---

From: "Beni Cherniavsky" <[email-masked]>
Date: Fri, 27 Oct 2006 15:18:32 +0200

> keyword as conveniently as one can using a man page.
``info foo | less`` gives you the whole manual in one document.  But
this loses hyperlinks and gains nothing.

As amit says, `Ctrl-S` and `/` work accross sections in the standalone
`info` reader.  `i` searches the index which is usually high-quality.

> I could never get the hang of the "info" command line. :-)
`pinfo` is friendlier but less powerful.  Browser access (e.g. dwww)
is probably your best option today.

> level of integration that I'm looking for.
What's missing?

-- 
Beni Cherniavsky <[email-masked]> (I read email only on weekends)