www.delorie.com/djgpp/bugs/show.cgi   search  
Bug 000108

When Created: 08/23/1996 15:13:05
Against DJGPP version: 2.00
By whom: Bob.Weaver@NAU.edu
Abstract: Poor UI for newbies, wrong examples and instructions
Hi--
I've just gotten v2.00 installed and working, and am in the one-time-only
position of commenting on stuff I'll either take for granted or ignore
later, so here goes:

1. Finding the entry path was fun--newbies need to read the FAQ to find the
docs they should read first.

2. I couldn't get a "hello.cpp" working with iostreams.h, though I could with
stdio.h.  The readme.1st shows as its compile example
   gcc myfile.c -o myfile.exe -lm
(notice what's missing here if myfile includes iostream.h?  The mail archives
saved me grief on this one--hoho was that someone's reply said, "This question
appears here too often.")

3. Info is a twisted beastie, partly because of its Unix heritage:
  A. Tutorial speaks incorrectly of Delete key use--
     1. Delete key on a PC doesn't do anything.
     2. Backspace key SOMETIMES works as expected: When tutorial says
        (in Help-^L node), "Now try typing a Space (afterward, type a
        Delete to return here)," Delete doesn't--it shoots user into
        "Basic Commands in Info Windows".
  B. Up-arrow, Down-arrow behavior is counterintuitive; moves one line
     at a time onscreen as expected, but then at top or bottom scrolls
     neither one line nor one screen but 1/2 screen.  (Ergonomics: a
     one-line scroll is almost a smooth scroll, easy to follow; failing
     this, a jump causes the eye to move to the top of the screen looking
     for the next line--it ain't there.)
  C. Menuing is execrable--there are three lines pointing to the same node
     in the tutorial example, and each one behaves differently!  Moving
     to the line and pressing enter gets, respectively for
       "*Foo"  says, "No cross references in this node."
       "*Bar"  says, "The reference disappeared! (Bar)."
       "* Help_Foo::"  actually goes to the subtopic.
     Similar madness exists if 'm' is pressed instead of enter, as follows:
       "*Foo"  says "Menu item:", hitting <Enter> fails.
       "*Bar"  says "Menu item (Bar):", <Enter> begets the above *Bar msg.
       "*Help_Foo::"  says "Menu item (Help_Foo)", <Enter> jumps to node.
  D. Using "f cross" per the tutorial worked, but the tutorial says to use
     'l' (ell) to get back; doesn't work.  I'd previously menued around and
     the thing skipped (backwards) over the tutorial node to as.info/top.
     I tried this more than once; it was consistent.

Please be aware that I'm GREATLY impressed with how well things have gone so
far--compared to these relatively trivial bugs, Borland C++ v4.52 stinks!
I'm hoping that passing this stuff back to you will help you make things
even cleaner, in an age when even the commercial OSes and development
systems are getting crappier instead of better.

Onward to fixes....

Solution added: 08/23/1996 15:21:16
By whom: Bob.Weaver@NAU.edu
1.  Point at the readme.1st file in the djgpp html page, as well as the
"What to Download" section of faq018.html and the outside QuickStart Guide
(I found one at www.cs.utexas.edu/users/dbarrett/dm/c-c++/djgpp.html)

2. In readme.1st under "Compilation", change
     gcc myfile.c -o myfile.exe -lm
   to
     gcc myfile.c -o myfile.exe -lgpp

3. Go through the Info tutorial as a newbie would (betcha haven't for
   awhile) and clean up the tutorial text and the code to support it
   so that it works well, cleanly and as described in a DOS environment
   (see the bug report for details).

Thanks for listening--
Bob

Note added: 11/21/1996 20:13:09
By whom: ">"John M. Aldrich"
The above solution is not entirely correct.  When compiling a C program, it is
unnecessary and possibly counterproductive to link libgpp.a, a C++ library.  The
"readme.1st" should list separate instructions for compiling C and C++.  Also,
it should give specific examples of the correct filename extensions to use for
C and C++ files, judging by the number of questions we have had on the ng about
this exact topic.

Note added: 12/29/1996 07:02:14
By whom: eliz@is.elta.co.il
IMHO, the name of the file `readme.1st' speaks for itself.  I fail
to see how pointing to it from an HTML page will help, since people
aren't required to read the HTML docs before downloading.

The gripes about Info seem like they've been produced by a lot of
random keypresses at random points.  I will try to fix some of the
more obvious problems with the Info docs when I port Texinfo 3.10,
but since this isn't a DJGPP-specific package, we cannot do
everything we want.

The complain about the gcc command line example is due to problems
in reading comprehension: that example clearly speaks about a C
program (not C++).  A few lines below that, there's an example for
linking C++ programs, which uses gxx instead of gcc.  It's too bad
the user didn't read that far.

I don't agree with John's remark about separate examples for C and
C++, because then readme.1st will become a user's manual.  People
should not expect to find all the answers in the first file they
read.

Note added: 06/21/1997 15:57:09
By whom: graeme@interlink.or.jp
Bob,

In regard to your criticisms of Info's 'unique' user interface, you wouldn't
be the first to find it not to your tastes. The simplest advice is if you
don't like it, don't use it. Info is not the only way to read the docs.

The main djgpp faq comes ready-made in both html and plain text
formats, and the info files for all the tools and libraries can easily be
converted to text files too. Here's how:

Say you have installed djgpp in the '\djgpp' directory of one of your
drives.

Change to the main djgpp directory:

C:\> cd \djgpp

Create a 'doc' subdirectory, if it doesn't already exist:

C:\djgpp> md doc

Change to the 'info' directory:

C:\djgpp> cd info

Run the magical 'sed' command:

C:\djgpp\info> dir /b *.inf | sed -e 's/\(.\+\)\.\(.\+\)/info -f \1.\2 -o ..\/doc\/\1.txt --subnodes/' > inf2txt.bat

This produces a batch file to convert all the existing info files in to text
files and put them in the 'doc' directory. Now run the batch file (it won't
modify the original info files):

C:\djgpp\info> inf2txt

That's it! You now have all the documentation in beautiful, glorious,
ASCII. Just view any of the newly created '.txt' files with your favorite
editor. The only drawback is that you don't get the handy hyperlinks.
On the other hand, your editor's text search facility is usually good
enough to find the key words your interested in.

The 'info' and 'sed' utilities can be aquired from the standard djgpp
distribution, in txi390b.zip and sed118b.zip respectively.

Note added: 04/13/1999 08:00:56
By whom: eliz@is.elta.co.il
Final notes:

  - Most of the gripes about Info are solved in Texinfo 3.12, and the rest
    will be solved in Texinfo 4 (to be released soon).

  - Sed has an Info docs as of v3.02.

  - README.1ST has been greatly improved, and the FAQ points to it.

So I think all of the issues were addressed, and I'm closing this report.

Fixed in version on 04/13/1999 08:00:24
By whom: eliz@is.elta.co.il



  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2010   by DJ Delorie     Updated Jul 2010