Re: Two New Software-Related Ideas

On Wednesday 25 October 2006 01:19, Amit Aronovitch wrote:
> 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.

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.

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

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.

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

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

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

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

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

Yes.

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

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

>
> ----------------------------
>
> (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?

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

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

-- 

---------------------------------------------------------------------
Shlomi Fish      shlomif-ik1l9ssToec+JF/[email protected]
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.


 
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/