[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: SEUL: Documentation: info & postscript

> First, the GNU info program, by which one is supposed to read the GCC
> and GDB docs.  Personally, I'm pretty frustrated with the thing.  I've
> done part of the "tutorial" and learned some of its basic features (but
> that was several days ago so I'd have to do it again should I need to
> remember them), but then got fairly turned off.  Why should I have to
> learn a sadistically unintuitive program to view the docs?  This very
> much discourages RTFM.

I had the same reaction every time I tried to use it.  It seems to be Emacs 
on a diet (making info near death from malnutrition, to follow the metaphor).
The problem with that is that info is just as 'intuitive' as Emacs, that is 
to say, not at all.

> So my main question for this is:  Is there any way to get GCC/GDB docs
> in ASCII or HTML so I can browse them using mc or lynx?  If not, is
> there a way to convert them?  I have done some searches on this without
> much success.

There is undoubtedly something out there that will do this, we just have to 
find it.  At least the info format is hypertext, if hard to use.

Also, you will find that if you man(1) certain GNU user utilities, you will
find the following notice:

       This documentation is no longer being maintained  and  may
       be inaccurate or incomplete.  The Texinfo documentation is
       now the authoritative source.

This is baaaad!  AT&T and friends developed man(1) for a reason!

> Also, PostScript.  I just downloaded EZWGL, the GUI toolkit, and figured
> I'd play with it some.  It comes with PS docs.  I have two programs to
> view PS files: one that comes with RedHat's X distribution, and then
> bmv, which I downloaded and compiled.  Both of them have somewhat
> awkward browsing, and I usually have a very hard time getting the width
> of a page to fit on the screen.  So I have to scroll right and left with
> every line I read.  Needless to say, that is not cool.

PostScript can be viewed with Alladin Ghostview, which isn't exactly GPL'd if 
IIRC, though we can still use the GNU version, which is downrev'd and buggy, 
again IIRC.

For discussion fodder, this is what twoducks, luka, and I discussed once upon
a time in IRC (logs will be available RSN):

We'd like to have a 'help browser', somewhat akin to the Doze help system 
(3.1, with some of the features of 95's).  It would be mighly modular.  The 
main binary would provide only the basic services, including the API for 
applications to deal with, the menu, and the modular infrastructure.  The 
bulk of the system is provided by plugin-style 'viewers'.

The primary viewer will be based on HTML or possibly the SDOC
(http://www.seul.org/doc/structure/seuldoc/seuldocspec.html - not current) 
mutation thereof.  Eventually, all the documentation for all the packages 
that ship with SEUL would be in this format.

There will also be active extensions to this format, which will be some */tk 
language.  This will allow help documents to take an active role in getting 
the user where they want to go.  In fact, we discussed the possibility that 
administration stuff (the non-everyday tasks) could be encapsulated by this 
system, creating a sort of wizard environment...

The advantage to the plugin method is that things like Ghostview can 
theoretically be encapsulated and plugged into the help browser.  We can then 
maintain the same general interface for everything.  This also allows 
applications or suites that already have their own help system to make slight 
modifications and simply plug directly into our environment, either 
postponing or avoiding all-together the conversion to HTML/SDOC.

As far as an API, each application would be able to call the help system via 
a standard library call (in libhelp.so for instance), as well as control it.  
Say you click on help (context sensitive help, if possible), and a help 
browser window pops up displaying all the pertinent information (unlike doze* 
that says absolutely nothing beyond the obvious: "is your printer plugged in?")
So you go and follow a link or two in that window, find what you need, and go 
back to work, but forget to close the window.

You then go work on another app, and need help there.  You click on help, the 
existing browser pops up and switches to the new help page.  But say instead 
of forgetting about the help window and it's contents from the previous app, 
you were actively using them.  Well, the new help (unless you specifically 
told it otherwise) would conveniently load the new page over what you were 
browsing.  No problem, use the 'split to previous' button.

The 'split to previous' button would create a new window (same process,
ideally) that would then load the previous page you were in.  The page 
history would be identical, as in Navigator when you create a new browser 
window.  This allows the slightly more savvy users with the ability to manage 
all the help windows they want without getting lost in hypertext.

twoducks (Ken Duck) hopefully will have more in-depth information on this 
topic soon, though he is planning 'the big day' (hence the 'two' in twoducks),
so don't pester him too much... ;-)


        Erik Walthinsen - Programmer, webmaster, 3D artist, etc.   __
  __                                                              / /\
 /  \           omega@sequent.com         Work: (503)578-5314    / /  \
|    | M E G A  omega@aracnet.com         Home: (503)281-4281   / / /\ \
_\  /_          psu12113@odin.cc.pdx.edu  Majoring in CS       / / /\ \ \
                                                              / /_/__\ \ \
Omega Station: http://www.aracnet.com/~omega/                /________\ \ \
     Info on Linux, Graphics, Descent, Laptops, etc.         \___________\/

Simple End User Linux Mailing list
To be removed from this mailing list send a message to majordomo@txcc.net
with the line
unsubscribe seul-project
in the body of the letter.