Re: Documentation (Was: Re: [1.2 installation]: how to tell X to ...)
> From: Fabien Ninoles <ninf01@castor.gel.usherb.ca>
...
> On Wed, 15 Jan 1997, Daniel S. Barclay wrote:
...
> > Good. :-) I HATE that "feature" of Windows 95. ...
...
> > Oh...yeah; sorry. Okay.
> > #undef HATE_MICROSOFT_MODE
> >
>
> have you succesfully compiled anything after this? ...
No, although I do boot Windows 95 to run Quicken.
>...
> Maybe Mhonarc can do little thing about it but I'm talking about an
> almost concised flames-cleared digest of the list, with tools to browse
> throwout.
Yes, a moderated digest archive would certainly be easier to use that a full
archive.
> > If command "old_simple_x" is superseded by "new_fancy_x", then ideally
> > the documentation for old_simple_x that a user might run into (e.g., the
> > manual page) would say "don't forget that now there is new_fancy_x you might
> > want to use instead."
> >
> > I _have_ seen that on a few Unix manual pages or somewhere similar (maybe
> > GNU info pages for the C library, documenting routines that still exist
> > but for which better replacements exist.)
> ...
> The case you cite only happens when a program are just included for
> backward compability. But most of the time, you really have two or more
> alternatives equally supported to do the same thing. Debian make lot of
> work to standardize and simplify everything. Configuration and
> Documentation are still the most discussed subject on the lists, but
> standard and freedom seems to be a little bit opposed sometime.
I just wish for cross pointers (or some other way to know what the choices
are), not any encroachment on freedom to choose, I don't think.
> > > > 3. Keep in mind that it's hard to keep up with constantly-changing
> > > > documentation. ...
> > > > I would think that direct-lookup on-line documentation like manual
> > > > pages or GNU info pages would be used on a continuing basis, so
> > > > I would hope that all new information would make it into that
> > > > reference documentation, and hopefully a few pointers to new,
> > > > alternative, or add-on things could be included too.
> > >
> > > That's why Changelogs exists.
> >
> > I'm trying to find a way to consolidate the information. If I read a
> > manual page for something, then I also have to check the /usr/doc
> > directory...and any GNU info pages...and then I have to get the source
> > package to check the ChangeLog (or are ChangeLogs included in binary
> > Debian packages).
>
> HTML is the currently supported format for Debian doc. But is not so easy
Do you mean for Debian-specific documentation, or for most documentation
shipped in a Debian distribution? (If the latter, where is it?--I've missed
it.)
> to maintain. I don't won't to be the one who will have to translate all
> the XV doc in html (with significanted links and everything). Also, we
> need a good html search index too for browsing throw everything. dwww
> seems to be the nearest way to a solution but some work still have to be
> done.
Actually, give me a pointer to what HTML documentation you're referring to;
I'm not sure I haven't missed something.
> ...
> Missing useful info are considered as a bug in Debian (contrarely to the
> FSF). Any "little thing" like this would be really appreciate.
Yes, I plan to report specific things...well, when I get around to it.
Sometimes it's hard to get motivated to report all the specific problems,
because it seems that people don't back up a level to look at the source
of the problems, to fix the root causes and avoid many specific problems.
For example, regarding all those buffer-overflow security-problem reports:
It's the same error again and again. Instead of fixing individual buffers
that are too short, why isn't there a push towards using some common library
of string manipulation functions for string operations (including buffer
allocation)? Then the likelihood of these errors (security problems and
just plain old bugs) would be reduced faster than from just fixing one bug
at a time when it's noticed.
> > (Is there any documentation policy document, either for Debian or for
> > Linux generally, to which I should contribute any useful ideas I might
> > have?)
> >
>
> You'll find all the policy in the policy manual, a document you find in
> html format at /usr/doc/dpkg/policy.html/index.html in the dpkg-dev
> package or on the ftp-sites in the doc directory (yes, /pub/debian/doc
> not in /pub/debian/stable/binary-all/doc !)
Thanks. I'll take a look.
Daniel
--
This message was delayed because the list mail delivery agent was down.
Reply to: