Paul M. Foster (paulf@quillandmouse.com)
Sat, 15 Jan 2000 12:09:27 -0500 (EST)
On Thu, 13 Jan 2000, Aaron Turner wrote:
> On Thu, 13 Jan 2000, Paul M. Foster wrote:
> >
> > On Wed, 12 Jan 2000, Aaron Turner wrote:
> >
> > > On Tue, 11 Jan 2000, Paul M. Foster wrote:
> > >
> > > > On Tue, 11 Jan 2000, Kim Lester wrote:
> > > > >
> > > > > ODE Summary Report #1
> > > > > =====================
<snip>
> > You're probably right, and that seems to be the concensus: SGML > XML. I
> > don't quite know what DocBook is, but from what I understand it is a
> > certain DTD under SGML. Yes?
>
> Yep. You can buy or download the Orielly DocBook manual.
>
Downloaded the manual. It's now on my todo list. Heh heh.
<snip>
> > > What you're talking about is specifying in the doc spec a "document type"
> > > and allowing users to limit their queries by type. If you design your
> > > system well this is easy.
> >
> > No no. The way Debian does it, it works out that if you want to look at
> > something contained in the HOWTOs, you have to go into the HOWTO section
> > of the documentation. But you may not know whether what you want is in the
> > HOWTOs or not. That's one reason why the Debian system is klunky. The user
> > shouldn't have to specify the source for answering his question.
>
> I think we're miss-communicating. I'm saying allow them to limit queries
> by the type to reduce the number of hits, not seperate the content so they
> can't do a global search against all docs if they don't have a clue where
> to look.
>
Ah. Got it.
<snip>
> > Hmm. That may be the crux of the problem. Is that what this project is
> > about? That seems impractical to me, because of the example I gave
> > above. Joe will update his tarball with his new man page, and you'll need
> > to be sure you know when it's been updated, so you can translate it into
> > your format and put it in your repository. At that point, versioning
> > _does_ become important.
>
> I don't know if Joe will stop writing man pages and start writing ODE.
> If he does then great. If not, then nothing we can do about it.
>
That was an exaggeration. If we can convince him to write in ODE format,
then so much the better. But there will be guys who just won't switch, and
we'll need to be able to suck in their stuff, too.
> > This sounds like LinuxKB to me. You're talking about all docs in one
> > format, then converted to others for use. But if you have it all in this
> > cool format, why convert it? Just build or find a program that uses it in
> > its native format and forget about man pages and such altogether.
>
> Actually the LinuxKB is about converting all docs from their native format
> to html. This actually sucks because it limits the power of the site, but
> since there is not a standard, we're SOL. The ODE is about the opposite,
> getting all docs writing in the same format natively. At least that's the
> way I see it. Now if everyone uses the ODE, then that's really cool for
> the LinuxKB because we can take advantage of those standards (like the
> keywords META tag in HTML) to make the site more powerful.
>
Well, if you're right about ODE, that's different than what I thought.
Standardizing on a centralized doc format for all docs is a great idea,
but one that may be hard to execute, as in the "Joe" example above. It
should still be part of the plan, but I think that being able to eat docs
of any kind and spit them out in one browsable format is more practical in
the short term.
> Still though, it's good to convert ODE to something like man, because
> everyone has a man page viewer today and will have one for a long long
> time. Not everyone will have a ODE viewer for some time though, and it
> isn't likely to ever run on lower end systems very well.
>
Well, I sort of take a broader look. Linux has done some interesting
things for the broader Unix world, like the FHS. I don't think it's
impossible that we could create a new standard for Linux/Unix documents,
such that you wouldn't find man pages anymore. Or at least if you typed
"man ls" you'd be firing up the ODE browser and looking at the ODE
documentation. If you're just talking about the docs on a local machine, a
tool like Lynx could be made to browse the stuff. And even if we leave the
man pages and info docs on the system, we could still have something index
it. Then when the user types "man ls", Lynx fires off a cgi that uses the
index to decode the original man pages or somesuch. Just some ideas. But
in the end, I think it's possible that we could fundamentally change the
way documentation is stored on a system, etc.
This sort of sounds like the opposite of what I said above, but not
really. There are two prongs, as I see it. The "let's get all the docs
natively in one format and get the doc writers to agree on it", and the
"let's suck any kind of doc into our format, index it and spit it at the
user". The former is more long-term and more difficult. The latter is more
short term and easier.
> > Again, this looks like the difference between docs as viewed by LinuxKB
> > and local docs as viewed by a local user on his local machine. Which
> > approach is ODE looking at? Or both?
>
> I would assume both. Not doing both is rather dumb IMHO. I'm only
> advocating that whatever we do, we do our best to support remote
> centralized repositories like the LKB.
>
I think LKB will benefit no matter what approach is taken. Can't see how
they wouldn't.
Paul Foster
This archive was generated by hypermail 2.0b3 on Sat Jan 15 2000 - 11:03:48 EST