Loading ...
Sorry, an error occurred while loading the content.
 

Re: [hackers-il] Two New Software-Related Ideas

Expand Messages
  • Shlomi Fish
    ... 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
    Message 1 of 12 , Oct 25 9:24 AM
      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 <aronovitch@...> Mailed-By:
      > gmail.com
      > To: hackers-il@yahoogroups.com
      > 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@...> 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@...
      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.
    • Amit Aronovitch
      ... 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
      Message 2 of 12 , Oct 26 2:20 AM
        On 10/25/06, Shlomi Fish <shlomif@...> wrote:

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

        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)
        > at gnu.org.
        >

        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.

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

        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.
      • Beni Cherniavsky
        ... ``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
        Message 3 of 12 , Oct 27 6:18 AM
          On 25/10/06, Shlomi Fish <shlomif@...> wrote:
          > 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.
          >
          ``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.

          > >
          > > 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. :-)
          >
          `pinfo` is friendlier but less powerful. Browser access (e.g. dwww)
          is probably your best option today.

          > >
          > > 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.
          >
          What's missing?

          --
          Beni Cherniavsky <cben@...> (I read email only on weekends)
        Your message has been successfully submitted and would be delivered to recipients shortly.