Re: Two New Software-Related Ideas

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 protected]>	Mailed-By: gmail.com
To: [email protected]
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"
...

On 9/19/06, Shlomi Fish <shlomif-ik1l9ssToec+JF/[email protected]> wrote:
> 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
>


 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/hackers-il/

<*> Your email settings:
    Individual Email | Traditional

<*> To change settings online go to:
    http://groups.yahoo.com/group/hackers-il/join
    (Yahoo! ID required)

<*> To change settings via email:
    mailto:[email protected] 
    mailto:[email protected]

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/