Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
From: [EMAIL PROTECTED] In a message dated 3/22/99 10:21:50 AM Central Standard Time, [EMAIL PROTECTED] labs.com writes: Force of habit, I suppose Maybe it's time to remove the man pages for those programs that also have info pages, eh? Don't remove the manpages. And don't start an info vs. man war, either, please! I've no intention of starting a flame war - but the fact remains, if the man pages are no longer being supported by developers, there's no sense including them in the man pages package. It just adds to the confusion. ^ Not when they point to the info pages (or other documentation). Daniel
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
HM == Hamish Moffatt schrieb am 24 Mar 1999 23:19:54 +0100: HM IMHO, the info browser (in emacs or standalone) adds little HM functionality over a plain HTML document, except that it is much HM less accessible for non-emacs users. I disagree. What if you don't have lynx installed and _need_ the documentation ? How do you access KDE-information for example without a working browser - well, you have to use less/more/cat just as with info pages. The main difference is not that info has substantially more to offer than HTML but that the info pages were there a long time before HTML hit the scene. There _are_ a lot of people who like using info (me, for example, as I love the info capabilities of Emacs) and I would be really annoyed if support for this format would be dropped. Holger -- --- http://www.coling.uni-freiburg.de/~schauer/--- Kuenstliche Intelligenz ist also genau dann moeglich, wenn Turing-Maschinen fruehstuecken koennen und nicht gerade Semesterferien sind.-- Sven Türpe in de.sci.informatik.ki
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
On Tue, Mar 23, 1999 at 10:24:29AM +0100, Holger Schauer wrote: MB == Mark Brown schrieb am 23 Mar 1999 03:32:21 +0100: MB everything-HTML conversion seems to be the most likely route MB for those that want a standard interface at present. I am strongly against having a _single_ interface to documentation. Diversity is a good thing, IMHO, especially in this case. As am I. IMO man pages serve as a quick thorough overview and should be as compact as possible. Info pages serve IMO a different need: they should provide detailed information, perhaps for some more obscure or advanced features. If _then_ somebody wants an html-interface, fine, let him have a converter from man2html, texi2html, and perhaps a2html. Sounds familiar ? That's roughly what the dwww does and what is being suggested - I don't imagine that anyone wants HTML access only, as it tends to loose a lot of the information in the original formats. Personally I find it to be the worst format out there for documentation, but perhaps that's just me. -- Mark Brown mailto:[EMAIL PROTECTED] (Trying to avoid grumpiness) http://www.tardis.ed.ac.uk/~broonie/ EUFShttp://www.eusa.ed.ac.uk/societies/filmsoc/
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
On Tue, Mar 23, 1999 at 10:24:29AM +0100, Holger Schauer wrote: IMO man pages serve as a quick thorough overview and should be as compact as possible. Info pages serve IMO a different need: they should provide detailed information, perhaps for some more obscure or advanced features. If _then_ somebody wants an html-interface, fine, let him have a converter from man2html, texi2html, and perhaps a2html. Sounds familiar ? IMHO, the info browser (in emacs or standalone) adds little functionality over a plain HTML document, except that it is much less accessible for non-emacs users. I read info documents with less; the best part about them is how they're almost completely plain text. Hamish -- Hamish Moffatt VK3TYD [EMAIL PROTECTED], [EMAIL PROTECTED] Latest Debian packages at ftp://ftp.rising.com.au/pub/hamish. PGP#EFA6B9D5 CCs of replies from mailing lists are welcome. http://hamish.home.ml.org
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
On Mon, Mar 22, 1999 at 11:55:08AM -0800, Kenneth Scharf wrote: Now isn't there a utility that will create 'man' pages out of 'info' ones? If so then at least some current information may be presented in man format for those of us that are more used to the 'older' This would be hard - the structures of man pages and info files are totally different, and automatically processing and arbatary texinfo source into man is going to be messy. everything-HTML conversion seems to be the most likely route for those that want a standard interface at present. -- Mark Brown mailto:[EMAIL PROTECTED] (Trying to avoid grumpiness) http://www.tardis.ed.ac.uk/~broonie/ EUFShttp://www.eusa.ed.ac.uk/societies/filmsoc/
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
MB == Mark Brown schrieb am 23 Mar 1999 03:32:21 +0100: MB everything-HTML conversion seems to be the most likely route MB for those that want a standard interface at present. I am strongly against having a _single_ interface to documentation. Diversity is a good thing, IMHO, especially in this case. IMO man pages serve as a quick thorough overview and should be as compact as possible. Info pages serve IMO a different need: they should provide detailed information, perhaps for some more obscure or advanced features. If _then_ somebody wants an html-interface, fine, let him have a converter from man2html, texi2html, and perhaps a2html. Sounds familiar ? Holger -- --- http://www.coling.uni-freiburg.de/~schauer/--- Sometimes I think that the best evidence that there is intelligent life in the universe is that none of it has tried to contact us. -- Calvin
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
Olaf Rogalsky [EMAIL PROTECTED] writes: This would be wonderful!!! Only one single point from where to search for documentation. If you ever executed a command like find /usr -type f|xargs egrep -li 'proxy|squid' then you know, that a central point for documentation would be a great time saver. Olaf Rogalsky Try the package dwww, which has a single webpage for all of the docs (man, info, HOWTO, FAQ, /usr/doc ... you name it) on your Debian system, with a search capability. It's my Netscape home page (http://localhost/dwww/index.html). Greetings, joachim
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
I have to admit, there is a bit of truth to this, alot of people just don't have the time to read 18 different documents in 18 different locations. Man pages, info pages, FAQs, HOWTOs, mini-HOWTOs, READMEs, INSTALL docs, package descriptions... it is a bit daunting. I do feel that anyone installing anything shoud be up for some reading, but just how much reading is the question. I'm not even going to think about complaining about the amount of documentation, coming from systems that have zip, I know from experience how helpful good documentation can be. But I wonder if maybe there is a better way to organize the volumunous information given to us in a standard, easy to use, heirarchial fashion. What about this: for a start make sure that every package has a file in /usr/doc/package name that points to the available documentation, like * manual page blurp.1: short overview of command line options * info blurp.info.gz: extensive discussion of all options, and some examples * http://www.blurp.org: web site dedicated to blurp * see also the blurp-doc package In a similar vain it would be very helpful to have a file that lists configuration files that have an impact on the package, like this. /etc/conf.blurp /var/lib/blurp/blurp.history HTH, Eric Meijer This would be wonderful!!! Only one single point from where to search for documentation. If you ever executed a command like find /usr -type f|xargs egrep -li 'proxy|squid' then you know, that a central point for documentation would be a great time saver. But when talking about documentation, I must talk about man pages. Every (I really mean every) executable should have an up to date and complete man page. Unfortunately the gnu folks stick to info files. Info files tend to be lengthy and tedious, but most time I only need a comprehensive description of the command and its options. That's what a man page should be. Therefore I am a strong advocate of man pages, which ideally should have the following structure (sections in brackets [] are optional): Name: The name of the command. Synopsis: Syntax of the command. Description: Short, but complete description of what the command does. Options: List of all options and description of how they alter the behaviour of the command. [Exit Status]: Sic [X-Resources]: For X programs the list of X resources with description which are meant for user customization. [Environment]: List and description of environment variables, which are affected or which affect the command execution. Examples: List of a few examples showing the typical use of the command. Files: List of files which are in tight relation to the command, i.e. full path of the command and full path of configuration-, log-, etc files. See Also: List of related man pages. [Bugs]: List of known bugs. Version: Version number of the command with date of release. Authors: List of authors together with email addresses and/or web pages Of course this is not the last word spoken on what a man page should look like, but it might be a good starting point. Olaf Rogalsky \\|// (. .) +-oOOo-(_)-oOOo+ I Dipl. Phys. Olaf Rogalsky Institut f. Theo. Physik I I I Tel.: 09131 8528440 Univ. Erlangen-Nuernberg I I Fax.: 09131 8528444 Staudtstrasse 7 B3 I I [EMAIL PROTECTED] D-91058 Erlangen I +--+
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
I also agree with the idea of having a single starting point for documentation. And something I kind of wonder about - why are there always so many documents for a given program? Can't they be combined into one document devided into sections? With info pages, you can get to any specific section quickly and cleanly, this seems like a good way to get to the FAQ, or program doc, or release notes.. And curious.. alot of the man pages say they are no longer supported, that info is the definitive source of documenation. So, why does everyone here say read the man page? :) Force of habit, I suppose Maybe it's time to remove the man pages for those programs that also have info pages, eh? -Jay
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
[EMAIL PROTECTED] writes: Force of habit, I suppose Maybe it's time to remove the man pages for those programs that also have info pages, eh? Don't remove the manpages. And don't start an info vs. man war, either, please! -- +- pgp key available --+ | Dale E. Martin | Clifton Labs, Inc. | Senior Computer Engineer| | [EMAIL PROTECTED]|http://www.clifton-labs.com | +--+
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
In a message dated 3/22/99 10:21:50 AM Central Standard Time, [EMAIL PROTECTED] labs.com writes: Force of habit, I suppose Maybe it's time to remove the man pages for those programs that also have info pages, eh? Don't remove the manpages. And don't start an info vs. man war, either, please! I've no intention of starting a flame war - but the fact remains, if the man pages are no longer being supported by developers, there's no sense including them in the man pages package. It just adds to the confusion.
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
[EMAIL PROTECTED] writes: I've no intention of starting a flame war - but the fact remains, if the man pages are no longer being supported by developers, there's no sense including them in the man pages package. It just adds to the confusion. Not true. If the manpage says this manpage is out of date, see the info pages then I've learned _exactly_ what I need to know from the manpage. If there's no manpage there then I'll just be confused and wondering why there's no documentation. Later, Dale -- +- pgp key available --+ | Dale E. Martin | Clifton Labs, Inc. | Senior Computer Engineer| | [EMAIL PROTECTED]|http://www.clifton-labs.com | +--+
Re: Documentation suggestion (was Re: Slink upgrade and xwindows
Could someone tell me how to read info pages / find out what info pages are available? I know this is probably a dumb question, but I don't seem to have an info topic command - so does info use a different kind of syntax to man or is it a special package or what? Thanks! Tim [EMAIL PROTECTED] writes: I've no intention of starting a flame war - but the fact remains, if the man pages are no longer being supported by developers, there's no sense including them in the man pages package. It just adds to the confusion. Not true. If the manpage says this manpage is out of date, see the info pages then I've learned _exactly_ what I need to know from the manpage. If there's no manpage there then I'll just be confused and wondering why there's no documentation. Later, Dale -- E-Mail: Timothy Hospedales [EMAIL PROTECTED] Date: 22-Mar-99 Time: 15:06:56 This message was sent by XFMail Powered by Debian GNU/Linux. --
Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
In a message dated 3/22/99 10:21:50 AM Central Standard Time, [EMAIL PROTECTED] labs.com writes: Force of habit, I suppose Maybe it's time to remove the man pages for those programs that also have info pages, eh? Don't remove the manpages. And don't start an info vs. man war, either, please! I've no intention of starting a flame war - but the fact remains, if the man pages are no longer being supported by developers, there's no sense including them in the man pages package. It just adds to the confusion. Now isn't there a utility that will create 'man' pages out of 'info' ones? If so then at least some current information may be presented in man format for those of us that are more used to the 'older' format. Hey there are some people out there that DON'T like to use EMACS! (I'm s l o w l y learning how to use it under protest). == Amateur Radio, when all else fails! http://www.qsl.net/wa2mze Debian Gnu Linux, Live Free or . _ DO YOU YAHOO!? Get your free @yahoo.com address at http://mail.yahoo.com
Re: Documentation suggestion (was Re: Slink upgrade and xwindows
Timothy Hospedales [EMAIL PROTECTED] writes: Could someone tell me how to read info pages / find out what info pages are available? I know this is probably a dumb question, but I don't seem to have an info topic command - so does info use a different kind of syntax to man or is it a special package or what? Thanks! Tim I use CTRL-h i in xemacs, personally. That lists them all. Later, Dale -- +- pgp key available --+ | Dale E. Martin | Clifton Labs, Inc. | Senior Computer Engineer| | [EMAIL PROTECTED]|http://www.clifton-labs.com | +--+
Re: Documentation suggestion (was Re: Slink upgrade and xwindows
Timothy Hospedales wrote: Could someone tell me how to read info pages / find out what info pages are available? I know this is probably a dumb question, but I don't seem to have an info topic command - so does info use a different kind of syntax to man or is it a special package or what? You can also use the program tkinfo in X. Kent
