Re: Documentation (Was: Re: [1.2 installation]: how to tell X to ...)
-----BEGIN PGP SIGNED MESSAGE-----
First my apologizes about being a little "spicy" in my respond. I don't
know which kind of meat I was eating this day... :)
On Wed, 15 Jan 1997, Daniel S. Barclay wrote:
>
> > From: Fabien Ninoles <ninf01@castor.gel.usherb.ca>
>
> > On Tue, 14 Jan 1997, Daniel S. Barclay wrote:
> >
> > > However, how are users supposed to find out about those things?
> > > (Not to say your suggestion is bad, but to address how to make that
> > > information easier to find.)
> >
> > What about a "Tip of the day" package in place of fortune
> > (just kidding ;)
>
> Good. :-) I HATE that "feature" of Windows 95. (I want a f**cking manual
> so I can look up what I need now and/or so I can read whole sections and know
> I know how to do whatever comes up in the future, without having to wait
> for random tip selection to have covered everything in the tips list--which
> is pretty short anyway.)
>
> Oh...yeah; sorry. Okay.
> #undef HATE_MICROSOFT_MODE
>
have you succesfully compiled anything after this? Doubt it except if you
put this line:
#define DEBIAN_LINUX YES ;)
> >
> > That's why Archive Mailing List are for. Did you suggest we should packed
> > it for local use and search?
>
> No, I wasn't suggesting that.
>
> Hmm. No, I don't think I'd want that--too much to search through and I don't
> think you could search it very reliably.
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.
>
> 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.)
>
> Obviously, not much of this is going to happen, at least not in internal
> documentation.
>
> Some documents, such as the HOWTO documents, do get updated a while.
> Maybe something based on or connected to them would be good.
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.
> > > 3. Keep in mind that it's hard to keep up with constantly-changing
> > > documentation. That is, a new user probably would read all
> > > the HOWTOs, README files, etc., to get started, but after that,
> > > it's impossible to re-read everything just to find the changes.
> > >
> > > 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
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.
> That remind me of another documentation problem resulting from not thinking
> about how the software is installed:
>
> The diald manual page refers the reader to diald.h. Now why should I have
> download and install the diald source package just to learn which bits
> get which debugging information? Not a big or stupid mistake or anything,
> but it appears that the author was only thinking of the case in which
> users build diald themselves, and have the source code lying around.
>
> If we thought a little bit more about what we're doing...
> (I've seen a number of cases of little things that could have been
> better with just a little thought.)
Missing useful info are considered as a bug in Debian (contrarely to the
FSF). Any "little thing" like this would be really appreciate.
>
> (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 !)
Hopes this can help.
- ---------------------------------------------------------------
Q: Can someone please explain to me the difference between
Java and C?
A: Java is an island north of Australia, whereas C is the
Roman numeral for 100
- (Ken Nicolson, comp.lang.c)
- ---------------------------------------------------------------
Fabien Ninoles aka le Veneur || Running Debian-Linux
Ninf01@gel.usherb.ca || Lover of MOO, mountains,
http://www-edu.gel.usherb.ca/ninf01 || poetry and Freedom.
- ---------------------------------------------------------------
-----BEGIN PGP SIGNATURE-----
Version: 2.6.2
iQCVAwUBMt5zylX6fc7jcjhFAQEqbgQAoU7RcvYBukUlcMZRdXubnB1Y84mHCfLx
ieS2AUjrWhT80t5PitRN8ZGYLk5S4Xd/RCXiqtlsiYPeBw1tezjANcCqQiR22EB9
NG2XLCQRtlIfuJI33HbsAaLgEpkCylq8oe7p31det2fAWFJzw0mhtZCbiC06xWwY
MPB1X7lP2Bk=
=ccwX
-----END PGP SIGNATURE-----
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-user-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: