Re: ODE Summary Report #1


Gregory Leblanc (gleblanc@cu-portland.edu)
Tue, 11 Jan 2000 17:34:28 -0800


"Paul M. Foster" wrote:
>
> On Tue, 11 Jan 2000, Kim Lester wrote:
>
> >
> > ODE Summary Report #1
> > =====================
>
> What should our favored format be? Obviously, opinions vary. However,
> since we're trying to index information, and since presentation should be
> less important, I'd vote for XML. It is specifically designed to allow
> indexing of information, and has incredible flexibility. The writers of
> documentation needn't worry with what format we use, since we are
> translating from their format into ours. Real issue is what will make our
> indexing job the easiest? I'm inclined to think XML. And forget standards
> for XML. You actually don't need a DTD for XML, but we can come up with
> one if needed. After all, this is our internal format. Now, if you want
> others to write to this format, you'll have to make the DTD simple.

XML without a DTD is like getting a build your own thermo-nuclear weapon
without instructions. Even if it's a totally custom DTD (which I don't
think is a good idea either), we need to have a set of elements defined
so that it's useable. I like DocBook, but I'm not an expert by any
means.

>
> Do you want to be able to search the Red Hat package database as
> well? Like, "what package is file X in?"

This functionality is a part of the RPM tools and system already.

>
> One thing sorely lacking in Linux distros, which was commented on in
> previous posts, is the ability to ask, "What programs can I use to look at
> my mail with?"

This feature is something that SHOULD be a part of any package managing
format, but doesn't seem to belong to any. It should also be tied into
the documentation system so that you can get a decent idea of what the
features are of any given program before you install it.

> And "what does X program in Y directory do?" Quite often,
> these programs don't even have a doc file of any kind with them.

A good package managment system can tell you what that file belongs to,
and from there you can usually find some information on it, but it
should certainly be easier than it is.

>
> Is the plan to index things via some hierarchy, like the way man files are
> laid out, or the way the Dewey Decimal System works? If so, then we much
> exhaustively generate appropriate categories. Then the question is, can
> our indexing technology be smart enough to figure out from the
> documentation the categories into which the documentation falls? And what
> if we further subdivide the content of a single man page? Does the indexer
> do a good job with that as well? I'd love to see some suggestions on what
> categories we should use.

I don't feel that this is realistic. There have been attempts at this
made with RPM, on rpmfind.net. If you list programs by category, it's
impossible to find the program that you're looking for unless you put it
in a specific category yourself.

>
> Do we plan to include things like the kernel docs in our indexing? That
> is, do we plan to include some of the more arcane, less well-known
> documentation sources in our indexing?

Perhaps this could be an option like the old version of Windows Help had
(windows in NOT ALL bad), where you could adjust your search critera to
generate a "typical" index, a "complete" index, or a "custom" index
(those terms are slightly off, but you get the point).

>
> Language may not be that much of an issue. User defines an environment
> variable that specifies his native language, and we serve it to him in
> that language if it's available.

Some of this is already available for SGML DocBook, although I don't
understand how it works.

>
> Don't know how much importance versioning has in all this. If the user is
> using fetchmail 5.0, he probably will not care what fetchmail 4.2
> did. He/she will only be interested in the documentation for what's on his
> system. Maybe I misunderstand what is meant by versioning here.

I think that the idea behind versioning was more to do with versions of
the documentation system than with actual programs. A package should
come with general instructions/manuals that apply to that package, and
with specific ones that deal with the errata from that particular
release.

>
> Personally, I'd like to see all the docs distributed in ONE format and
> skip all the goofy alternate formats. Nothing's worse than calling "man
> foo" and finding out that GNU has decided they don't want to maintain the
> man pages anymore, and that the real up-to-date stuff is in info. Argh. I
> don't like the info format anyway. Just put it all in XML or SGML or
> something, and let the user access all of it that way. And if they want to
> type "man foo", then what they get is Lynx handing them an XML page for
> what they asked for. Of course, I'd like to see most Linux docs
> completely rewritten so that one doesn't need three PhDs from four
> universities to understand it. Too radical, I know. </rant>

Wonderful idea. You'd need some way to make other formats availabe on
demand, for times when you're dealing with a single-color, text only
display that doesn't support all of the features of your common file
format. Again, SGML and XML offer things similar to this, but not on
demand, and I don't know what tools are available for XML at this point.

>
> 1) We will work with existing doc formats, subset of which we must
> define. (Vote: man, info, SGML, tex, text.)

I don't understand what you're saying here.

>
> 2) We must define our native format (there's flame-bait!) (Vote: XML.)

Either SGML or XML, makes no difference to me. They're similar enough
to make my learning curve nil.

>
> 3) We must build/find formatters, black boxes that go from format X to
> our format.

And from our format to the actual display format, for cases where the
display is more limited.

>
> 4) We must define how much or how little work we wish to do in indexing.
> Do we want humans going through all the docs, marking them up for the
> indexer, or should the indexer be smart enough to figure it all out? Where
> do we draw the line or is there one?

This should be taken care of automagically for documents in our native
format.

>
> 5) We must define the categorization system.
>
> 6) We must define and find/build the indexer.
>
> 7) We must define the user interface. (Vote: browser, specifically Lynx as
> the lowest common denominator.)

I would have to say that I'd like to see it able to use lynx, but also
to be able to take advantage of the features that a GUI offers.

>
> 8) We must define how the user may search. (Vote: text, program name,
> keyword, topic/category, filename.)
>
> 9) We must prototype the system.
>
> 10) We must test it with live users.

Dead ones aren't helpful, and people actually working on the project
will not have a good perspective on useability. My brother is a full
time beta tester, I know how blind authors/programmers are to their
work.

>
> 11) We must convince other people to use/distribute it.
>
> All these are separate projects.
>
> I assume that we don't just intend to sit around and build standards. I
> assume that we intend to actually do some coding at some point. Yes?

There are some people who will be useless as coders (me), but will still
be able to offer insight. We will definately have to do some coding at
some point, in order to get tools that are satisfactory.

>
> If we want this thing to take forever, we should be obsessive about
> obtaining everyone's agreement. Otherwise, let's just build a better
> mousetrap, get most people to agree, and let the rest do as they like
> (they'll probably come around anyway).

This is true, but we should allow at least enough time for discussions
to bring out all sides of an issue before the coders actually start work
on it. This was done a LOT working with the GNOME mailer, Evolution.
        Greg



This archive was generated by hypermail 2.0b3 on Tue Jan 11 2000 - 20:36:03 EST