Discussion:
Debian GNU/Linux Reference Card under construction
W. Borgert
2004-04-15 10:34:56 UTC
Permalink
Hi,

for computer literate people, who either are new to Debian or are new to
any UNIXish system, I created a draft "reference card". The card has some
information on how to get help, the dozen most important shell commands,
some apt-get/apt-cache/apt-file and dpkg commands, as well as some more
specialised things. The criteria for me was: Which questions did I get
most often in the last four weeks? Now I like to get feedback, most
destructive criticism and other useful help:

1. Please look at the card and point out any errors. Nothing is worse
for a beginner than false information. {"To list your files type
rm -rf /", "Install Mandrake", ...)

2. There is still room for your favourite command/config file/whatever.
Tell me - I will add things, until the card is full. Maybe I use one
complete page (1/6 of the card) for the debian-installer (and FAI).

3. My English is broken. Could please somebody from Oxbridge or Camford
try to repair it?

4. As soon as the card is complete (or nearly so) and the "English" is
fixed, I will provide a German translation. I am interested in having
the card translated to Italian and other languages. Any volunteers?

Here is the stuff:
http://people.debian.org/~debacle/refcard.pdf (ISO A4 format)
http://people.debian.org/~debacle/refcard.dbk (DocBook/XML source)

PLEASE CC ME, because I read this list mostly via it's web archive.

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Oliver Kurth
2004-04-15 10:41:31 UTC
Permalink
Post by W. Borgert
Hi,
for computer literate people, who either are new to Debian or are new to
any UNIXish system, I created a draft "reference card". The card has some
information on how to get help, the dozen most important shell commands,
some apt-get/apt-cache/apt-file and dpkg commands, as well as some more
specialised things. The criteria for me was: Which questions did I get
most often in the last four weeks? Now I like to get feedback, most
1. Please look at the card and point out any errors. Nothing is worse
for a beginner than false information. {"To list your files type
rm -rf /", "Install Mandrake", ...)
- deborphan shows packages no other package depends on, ie. packages
which can be savely removed. Without any option, it shows only
libraries, with -a it shows all packages. 'Show orpaned packages' does
not say much... it may lead to the misunderstanding that those packages
are no longer maintained.

- 'dpkg -S file' shows which package a file belongs to. 'Search for
installed file' is misleading.

Greetings,
Oliver
W. Borgert
2004-04-15 16:46:26 UTC
Permalink
Post by Oliver Kurth
- deborphan shows packages no other package depends on, ie. packages
..
Post by Oliver Kurth
- 'dpkg -S file' shows which package a file belongs to. 'Search for
..

Thanks, I changed both.

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Andreas Tille
2004-04-15 10:52:41 UTC
Permalink
Post by W. Borgert
2. There is still room for your favourite command/config file/whatever.
Tell me - I will add things, until the card is full. Maybe I use one
complete page (1/6 of the card) for the debian-installer (and FAI).
Perhaps you might like to add Zope (because the Zope port is different from
default installation)

http://hostname:9673/

I do not use MySQL but I think it should be worth mentioning.

I would add to the help topic:
/usr/share/doc/<packagename>/README.Debian
in addition to "Find all documentation here".

The command sudo might be interesting to add (accompanied by the config file
line which lets "sudo <command>" work.

Regarding to the BTS you might perhaps add the links I mentioned at

http://people.debian.org/~tille/debian-med/talks/paper-cdd/debian-cdd.html/ap-bts.en.html

This are the top two questions regarding the BTS if I'm on exhibition boothes.

Are you aware of the Debian Flyer which is available at

http://cvs.infodrom.org/goodies/flyers/general/?cvsroot=debian

May be it makes sense to copy the style ...

Kind regards

Andreas.
W. Borgert
2004-04-15 17:18:30 UTC
Permalink
Post by Andreas Tille
Perhaps you might like to add Zope (because the Zope port is different from
default installation)
http://hostname:9673/
I'm not sure whether I will add that, because I never used Zope.
Btw. I will add id attributes to all tables, so that it will be easy
to create customised versions of the reference card.
If you send me a DocBook snippet about zope (<informaltable> identical
to the existing tables), I will add it to the source code, OK?
Post by Andreas Tille
I do not use MySQL but I think it should be worth mentioning.
Yes, but I'm not using it either. Same as Zope, if one sends me
a DocBook text snippet, I will add it to the source.
Post by Andreas Tille
/usr/share/doc/<packagename>/README.Debian
in addition to "Find all documentation here".
I will add this.
Post by Andreas Tille
The command sudo might be interesting to add (accompanied by the config file
line which lets "sudo <command>" work.
I will add sudo.
Post by Andreas Tille
Regarding to the BTS you might perhaps add the links I mentioned at
..
Post by Andreas Tille
This are the top two questions regarding the BTS if I'm on exhibition boothes.
I will include all three links.
Post by Andreas Tille
Are you aware of the Debian Flyer which is available at
..
Post by Andreas Tille
May be it makes sense to copy the style ...
Hm, it took a huge piece of my weekend to steal successfully the
layout from BSD, so I don't like to work on layout again. The only
thing I really want to do is to add foldmarks.

Thanks a lot!

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Andreas Tille
2004-04-16 07:48:26 UTC
Permalink
Post by W. Borgert
Post by Andreas Tille
Perhaps you might like to add Zope (because the Zope port is different from
default installation)
http://hostname:9673/
I'm not sure whether I will add that, because I never used Zope.
Btw. I will add id attributes to all tables, so that it will be easy
to create customised versions of the reference card.
If you send me a DocBook snippet about zope (<informaltable> identical
to the existing tables), I will add it to the source code, OK?
I'd suggest the following patch:

--- refcard.dbk.orig 2004-04-15 22:46:34.000000000 +0200
+++ refcard.dbk 2004-04-16 09:45:24.000000000 +0200
@@ -655,6 +655,12 @@
<entry align="left"><simpara>Web interface to printer
configuration.</simpara></entry>
</row>
+ <row id="zope">
+ <entry align="left"><ulink
+ url="http://localhost:9673">ZOPE</ulink> at
+ <literal>http://hostname:9673</literal></entry>
+ <entry align="left"><simpara>Web Application Server</simpara></entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
Post by W. Borgert
Post by Andreas Tille
I do not use MySQL but I think it should be worth mentioning.
Yes, but I'm not using it either. Same as Zope, if one sends me
a DocBook text snippet, I will add it to the source.
I do not use MySQL either and so some more educated person might like to
provide the patch.
Post by W. Borgert
Post by Andreas Tille
Are you aware of the Debian Flyer which is available at
..
Post by Andreas Tille
May be it makes sense to copy the style ...
Hm, it took a huge piece of my weekend to steal successfully the
layout from BSD, so I don't like to work on layout again. The only
thing I really want to do is to add foldmarks.
It's OK for me. I just wanted to suggest some kind of "Corporate Design".

Kind regards

Andreas.
Andreas Tille
2004-04-16 09:18:24 UTC
Permalink
Post by Andreas Tille
Post by W. Borgert
to the existing tables), I will add it to the source code, OK?
Why has Zope (a very specific CMS) to be on a *generic* reference card
for Debian newbies? All that should better be in /u/s/d/z/INTRO or so.
Users who might switch from other distributions or who installed Zope
manually might wonder about the port under which they might access Zope.
I though this would be interesting for *Debian* newbies (not for
Linux newbies in general). BTW, I do not expect that my *suggestion*
will be accepted, but it was an idea which came to my mind.
Post by Andreas Tille
Post by W. Borgert
Yes, but I'm not using it either. Same as Zope, if one sends me
a DocBook text snippet, I will add it to the source.
I do not use MySQL either and so some more educated person might like to
provide the patch.
When everybody provides a patch for everything, it will become a reference
_book_ in few weeks.
Sure.
But as a PostgreSQL user (and MySQL ignorant ;-) ) I might have the right
to ask why we mention *one* major DBS but ignore the other (- even if this
fits exactly my usage habits).

Kind regards

Andreas.
Gunnar Wolf
2004-04-16 19:42:06 UTC
Permalink
Post by Andreas Tille
Why has Zope (a very specific CMS) to be on a *generic* reference card
for Debian newbies? All that should better be in /u/s/d/z/INTRO or so.
Users who might switch from other distributions or who installed Zope
manually might wonder about the port under which they might access Zope.
I though this would be interesting for *Debian* newbies (not for
Linux newbies in general). BTW, I do not expect that my *suggestion*
will be accepted, but it was an idea which came to my mind.
Yes - It might be important to note that 'documentation regarding
specific packages can be found in /usr/share/doc/<package>/'. I agree
with Edward - A reference card must be short and will need to skip
many important details. Remember we have over 14000 binary packages in
Sid - A reference card should be only general to Debian. Zope should
have its own reference card. MySQL should as well. This one should be
specific to Debian (and basic Unix stuff, probably).
--
Gunnar Wolf - ***@gwolf.cx - (+52-55)5630-9700 ext. 1366
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF
Eduard Bloch
2004-04-16 09:09:20 UTC
Permalink
Moin Andreas!
Post by Andreas Tille
Post by W. Borgert
to the existing tables), I will add it to the source code, OK?
Why has Zope (a very specific CMS) to be on a *generic* reference card
for Debian newbies? All that should better be in /u/s/d/z/INTRO or so.
Post by Andreas Tille
Post by W. Borgert
Post by Andreas Tille
I do not use MySQL but I think it should be worth mentioning.
Yes, but I'm not using it either. Same as Zope, if one sends me
a DocBook text snippet, I will add it to the source.
I do not use MySQL either and so some more educated person might like to
provide the patch.
When everybody provides a patch for everything, it will become a reference
_book_ in few weeks.

Regards,
Edaurd.
--
Gott hat den Menschen erschaffen, weil er vom Affen enttäuscht war.
Danach hat er auf weitere Experimente verzichtet.
-- Mark Twain (eigl. Samuel Langhorne Clemens)
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Frank Küster
2004-04-15 11:09:38 UTC
Permalink
Post by W. Borgert
1. Please look at the card and point out any errors. Nothing is worse
for a beginner than false information. {"To list your files type
rm -rf /", "Install Mandrake", ...)
- mention that not only programs have manpages

- missing whitespace before [--help

- why not indent the second line of two-line commands?

- update-/any/ often are not _configuration_ commands, many of these are
rather called after some manual/scripted/GUIed configuration change
has been done.

- deborphan: What do you mean with "i.e. libraries"?

- /var/log: there are also user log files, e.g. ~/.xsession-errors
(which sometimes gets annoyingly big...)
Post by W. Borgert
2. There is still room for your favourite command/config file/whatever.
Tell me - I will add things, until the card is full. Maybe I use one
complete page (1/6 of the card) for the debian-installer (and FAI).
dlocate should be mentioned IMO.

Regards, Frank
--
Frank Küster, Biozentrum der Univ. Basel
Abt. Biophysikalische Chemie
W. Borgert
2004-04-15 17:43:54 UTC
Permalink
Post by Frank Küster
- mention that not only programs have manpages
Thanks, done.
Post by Frank Küster
- missing whitespace before [--help
I know, but I don't know how to change that :-(
Post by Frank Küster
- why not indent the second line of two-line commands?
I can try that, but I'm not sure how to do it.
Post by Frank Küster
- update-/any/ often are not _configuration_ commands, many of these are
rather called after some manual/scripted/GUIed configuration change
has been done.
Maybe I will delete this point entirely. It's not helpful
to newbies.
Post by Frank Küster
- deborphan: What do you mean with "i.e. libraries"?
I changed that description.
Post by Frank Küster
- /var/log: there are also user log files, e.g. ~/.xsession-errors
(which sometimes gets annoyingly big...)
Yes, but I don't know, whether it's enough to say "List the files
using "~/.[a-z]*", because there are lot of configuration files
and maybe some log files are in "~/.[a-z]*/...". Too bad, that
GNU or UNIX doesn't have a ~/etc/ and ~/log/ convention.
Post by Frank Küster
dlocate should be mentioned IMO.
dlocate is nice, but does it add value over dpkg -S or dpkg -L?

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Frank Küster
2004-04-15 19:03:25 UTC
Permalink
Post by W. Borgert
Post by Frank Küster
dlocate should be mentioned IMO.
dlocate is nice, but does it add value over dpkg -S or dpkg -L?
It's way faster (and it might be outdated...). Also, it saves a lot of
*s (and "s, of course), try "dlocate -l tetex" and compare with "dpkg -l
tetex".

Regards, Frank
--
Frank Küster, Biozentrum der Univ. Basel
Abt. Biophysikalische Chemie
Philip Miller
2004-04-16 02:51:59 UTC
Permalink
Post by W. Borgert
Post by Frank Küster
- update-/any/ often are not _configuration_ commands, many of these are
rather called after some manual/scripted/GUIed configuration change
has been done.
Maybe I will delete this point entirely. It's not helpful
to newbies.
There is one important update- command important to intermediate users:
update-grub. By default, debian-installer uses grub on i386, the majority
platform, and users need to run update-grub after installing a new kernel
for the new kernel to appear in the menu presented at boot time.

Perhaps, then, you should mention make-kpkg (found in kernel-package), the
Debian Way TM of building a kernel.

Philip Miller
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
W. Borgert
2004-04-16 07:09:29 UTC
Permalink
Post by Philip Miller
Post by W. Borgert
Post by Frank Küster
- update-/any/ often are not _configuration_ commands, many of these are
rather called after some manual/scripted/GUIed configuration change
has been done.
Maybe I will delete this point entirely. It's not helpful
to newbies.
update-grub. By default, debian-installer uses grub on i386, the majority
platform, and users need to run update-grub after installing a new kernel
for the new kernel to appear in the menu presented at boot time.
I will add update-grub.
Post by Philip Miller
Perhaps, then, you should mention make-kpkg (found in kernel-package), the
Debian Way TM of building a kernel.
I used to use make-kpkg in the past, but switched all my
machines to the standard Debian kernels. I'm not sure,
whether newbies will need this. OK, maybe if s/o is used to
build her own kernel, she will appreciate the convenience of
the kernel-package.

Cheers,
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Georg Neis
2004-04-16 11:31:43 UTC
Permalink
Post by W. Borgert
Post by Philip Miller
Post by W. Borgert
Post by Frank Küster
- update-/any/ often are not _configuration_ commands, many of these are
rather called after some manual/scripted/GUIed configuration change
has been done.
Maybe I will delete this point entirely. It's not helpful
to newbies.
update-grub. By default, debian-installer uses grub on i386, the majority
platform, and users need to run update-grub after installing a new kernel
for the new kernel to appear in the menu presented at boot time.
I will add update-grub.
How do you feel about adding update-alternatives?

Regards, Georg
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Gunnar Wolf
2004-04-16 19:48:47 UTC
Permalink
Post by W. Borgert
Post by Philip Miller
Perhaps, then, you should mention make-kpkg (found in kernel-package), the
Debian Way TM of building a kernel.
I used to use make-kpkg in the past, but switched all my
machines to the standard Debian kernels. I'm not sure,
whether newbies will need this. OK, maybe if s/o is used to
build her own kernel, she will appreciate the convenience of
the kernel-package.
I find make-kpkg one of the best features in Debian - Yes, I know few
people need to recompile the kernel, but -as I said in my past
message- this is something Debian-specific, and you don't need to get
deep in its usage. Try something like:

If you need to compile a custom version of the kernel for your
system, we advise you to use kernel-package. Documentation for its
usage can be found in 'man make-kpkg'. In short, it will automate
the various stages of building and installing a kernel into a
Debian package. You will usually call it with 'make-kpkg
--append-to-version mymachine --revision 1.0 --config menu
kernel_image'

It can even be shorter :)

Greetings,
--
Gunnar Wolf - ***@gwolf.cx - (+52-55)5630-9700 ext. 1366
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF
W. Borgert
2004-04-16 19:27:51 UTC
Permalink
Post by Gunnar Wolf
I find make-kpkg one of the best features in Debian - Yes, I know few
I used to think the same until I gave up kernel building :-)
Post by Gunnar Wolf
If you need to compile a custom version of the kernel for your
system, we advise you to use kernel-package. Documentation for its
usage can be found in 'man make-kpkg'. In short, it will automate
the various stages of building and installing a kernel into a
Debian package. You will usually call it with 'make-kpkg
--append-to-version mymachine --revision 1.0 --config menu
kernel_image'
Hey, I'm not aiming for the Pulitzer award :-) Sorry, that's
way to long. And make-kpkg is not used by admins on a daily
basis, I hope. E.g. at work we use Herberts kernels.

Cheers,
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
Adrian 'Dagurashibanipal' von Bidder
2004-04-15 11:13:13 UTC
Permalink
Post by W. Borgert
1. Please look at the card and point out any errors.
- apt-get [dist-]upgrade don't take packages

Comments:
- apt-cache search pattern
Does your intended audience know what you mean by 'pattern'?
- apt-cache rdepends
Same. I think usual dependencies are sort of intuitive enough to
understand, but I'm not so sure about rdepends.
- Is apt-file installed by default? If not, a pointer to the package to
install would be helpful. (Same for other non-standard commands.)
- deborphan
As for apt-cache rdepends: To understand what an orphan is, a quite
good understanding of package dependencies is needed.
- what's the different between poweroff and halt? They're probably not
both necessary.
- postgresql: point to pg_hba.conf, and perhaps add how to change
password for a user.
- man: '... every command and many configuration files have a manpage.'
- mailing lists: perhaps point directly to the user list?

Layout: Currently, many of the commands are wrapped, which makes them
IMHO hard to read. Instead of

apt-cache policy Show versions and
package-names priorities...

I'd find it much better if it were

apt-cache policy package-names: Show versions
and priorities...

(Something like an itemized list instead of a table). This would
probably safe some space, too.

Of course, this is entirely a matter of taste.

greetings
- -- vbi

- --
Today is Setting Orange, the 32nd day of Discord in the YOLD 3170
Andreas Tille
2004-04-15 11:30:47 UTC
Permalink
Post by Adrian 'Dagurashibanipal' von Bidder
- apt-cache search pattern
Does your intended audience know what you mean by 'pattern'?
- apt-cache rdepends
Same. I think usual dependencies are sort of intuitive enough to
understand, but I'm not so sure about rdepends.
- Is apt-file installed by default? If not, a pointer to the package to
install would be helpful. (Same for other non-standard commands.)
auto-apt is kind of cool and would complete this list nicely.

Kind regards

Andreas.
W. Borgert
2004-04-15 17:56:42 UTC
Permalink
Post by Andreas Tille
auto-apt is kind of cool and would complete this list nicely.
For me, auto-apt sounds a little bit scary. Too much magic.
I'm not sure, whether I will add that.

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Joe Wreschnig
2004-04-15 19:49:12 UTC
Permalink
Post by W. Borgert
Post by Andreas Tille
auto-apt is kind of cool and would complete this list nicely.
For me, auto-apt sounds a little bit scary. Too much magic.
I'm not sure, whether I will add that.
auto-apt is not really any more magic than apt-file, it's just a wrapper
around the same idea. Also, auto-apt can also do everything apt-file
can, but not vice-versa. So, I'd rather see auto-apt mentioned.
--
Joe Wreschnig <***@debian.org>
Andreas Tille
2004-04-16 07:39:23 UTC
Permalink
Post by W. Borgert
Post by Andreas Tille
auto-apt is kind of cool and would complete this list nicely.
For me, auto-apt sounds a little bit scary. Too much magic.
I'm not sure, whether I will add that.
Well, IMHO auto-apt is very cool to show of for newbees on a booth.

Imagine when I was on Cebit some random people asked me: Could you
please show me a Linux Office suite?

OK.

~> sudo auto-apt update # was done before
~> auto-apt -x -y run
$ openoffice

...

wait until OpenOffice was downloaded and installed
...
OpenOffice found German locale but no locale files instelled
-> wait until German support for OpenOffice was downloaded and installed
...
--> finally OpenOffice was fired up

This was *really* impressive for people who were used to find some CDs
they had to put in their box, handle "Please remove all running programs"
requests and reboot stuff.

IMHO such kind of reference card could contain something we can be proud of ...

Kind regards

Andreas.
W. Borgert
2004-04-15 17:37:01 UTC
Permalink
Post by Adrian 'Dagurashibanipal' von Bidder
- apt-get [dist-]upgrade don't take packages
Thanks, fixed.
Post by Adrian 'Dagurashibanipal' von Bidder
- apt-cache search pattern
Does your intended audience know what you mean by 'pattern'?
I replaced 'pattern' with 'search-string'. While this is not 100%
correct, it might be more clear for newbies. Gurus will know the
difference and are free to laugh.
Post by Adrian 'Dagurashibanipal' von Bidder
- apt-cache rdepends
Same. I think usual dependencies are sort of intuitive enough to
understand, but I'm not so sure about rdepends.
I removed that one entirely.
Post by Adrian 'Dagurashibanipal' von Bidder
- Is apt-file installed by default? If not, a pointer to the package to
install would be helpful. (Same for other non-standard commands.)
I added a hint.
Post by Adrian 'Dagurashibanipal' von Bidder
- deborphan
As for apt-cache rdepends: To understand what an orphan is, a quite
good understanding of package dependencies is needed.
I changed the description.
Post by Adrian 'Dagurashibanipal' von Bidder
- what's the different between poweroff and halt? They're probably not
both necessary.
AFAIK, halt doesn't switch off the system, poweroff does.
Post by Adrian 'Dagurashibanipal' von Bidder
- postgresql: point to pg_hba.conf, and perhaps add how to change
password for a user.
I'm too new to PostgreSQL, could you please provide for a short paragraph?
Post by Adrian 'Dagurashibanipal' von Bidder
- man: '... every command and many configuration files have a manpage.'
Added.
Post by Adrian 'Dagurashibanipal' von Bidder
- mailing lists: perhaps point directly to the user list?
Added.
Post by Adrian 'Dagurashibanipal' von Bidder
Layout: Currently, many of the commands are wrapped, which makes them
IMHO hard to read. Instead of
..
Post by Adrian 'Dagurashibanipal' von Bidder
Of course, this is entirely a matter of taste.
I'm not sure, whether I like the table or the description list better.
But I hacked on the layout much more than on the contents and I'm a
bit tired of layout work, so I will leave everything as it is.

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Adrian 'Dagurashibanipal' von Bidder
2004-04-15 19:00:19 UTC
Permalink
[no cc:s pls]
Post by W. Borgert
Post by Adrian 'Dagurashibanipal' von Bidder
- what's the different between poweroff and halt? They're probably
not both necessary.
AFAIK, halt doesn't switch off the system, poweroff does.
may depend on the kernel and the BIOS and ...

My experience is that halt switches off the power (environment
permitting). I've never used poweroff.
Post by W. Borgert
Post by Adrian 'Dagurashibanipal' von Bidder
- postgresql: point to pg_hba.conf, and perhaps add how to change
password for a user.
I'm too new to PostgreSQL, could you please provide for a short paragraph?
pg_hba.conf is documented well enough in the default file shipped that I
think a simple pointer will be enough ('/etc/postgres/pg_hba.conf -
define who has access to the databases). Passwords are changed at the SQL
console with "ALTER USER name WITH PASSWORD 'password';"

cheers
-- vbi
--
The content of this message may or may not reflect the opinion of me, my
employer, my girlfriend, my cat or anybody else, regardless of the fact
whether such an employer, girlfriend, cat, or anybody else exists. I
(or my employer, girlfriend, cat or whoever) disclaim any legal
obligations resulting from the above message. You, as the reader of
this message, may or may not have the permission to redistribute this
message as a whole or in parts, verbatim or in modified form, or to
distribute any message at all.
Eduard Bloch
2004-04-16 09:11:51 UTC
Permalink
Moin W.!
Post by W. Borgert
Post by Adrian 'Dagurashibanipal' von Bidder
- what's the different between poweroff and halt? They're probably not
both necessary.
AFAIK, halt doesn't switch off the system, poweroff does.
Lol. lrwxrwxrwx 1 root root 4 2004-04-15 09:56 /sbin/poweroff -> halt

Regards,
Eduard.
--
Benutzerfreundlichkeit, einfache Installation und lesbare
Fehlermeldungen mit Erklärungen und Vorgehensvorschlägen sind in der
Informatik immer noch wie der Yeti im Himalaja: Gerüchten zu folge
soll es sie geben."
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Daniel Kobras
2004-04-16 09:39:00 UTC
Permalink
Post by Eduard Bloch
Post by W. Borgert
AFAIK, halt doesn't switch off the system, poweroff does.
Lol. lrwxrwxrwx 1 root root 4 2004-04-15 09:56 /sbin/poweroff -> halt
Oh rats! lrwxrwxrwx 1 root root 4 Apr 6 09:48 /sbin/reboot -> halt

Daniel.
Julian Mehnle
2004-04-16 09:43:17 UTC
Permalink
Post by Eduard Bloch
Post by W. Borgert
AFAIK, halt doesn't switch off the system, poweroff does.
Lol.
lrwxrwxrwx 1 root root 4 2004-04-15 09:56 /sbin/poweroff -> halt
lrwxrwxrwx 1 root root 4 2004-04-12 15:57 /sbin/reboot -> halt

So what? /sbin/halt decides what to do based on the name used to call it.
Peter Mathiasson
2004-04-16 09:48:56 UTC
Permalink
Post by Eduard Bloch
Post by W. Borgert
Post by Adrian 'Dagurashibanipal' von Bidder
- what's the different between poweroff and halt? They're probably not
both necessary.
AFAIK, halt doesn't switch off the system, poweroff does.
Lol. lrwxrwxrwx 1 root root 4 2004-04-15 09:56 /sbin/poweroff -> halt
halt(8):

-p When halting the system, do a poweroff. This is the
default when halt is called as poweroff.

reboot(2):

LINUX_REBOOT_CMD_HALT
(RB_HALT_SYSTEM, 0xcdef0123; since 1.1.76). The message `System
halted.' is printed, and the system is halted. Control is given
to the ROM monitor, if there is one. If not preceded by a sync(2),
data will be lost.

LINUX_REBOOT_CMD_POWER_OFF
(0x4321fedc; since 2.1.30). The message `Power down.' is printed,
the system is stopped, and all power is removed from the system,
if possible. If not preceded by a sync(2), data will be lost.
--
Peter Mathiasson, peter at mathiasson dot nu, http://www.mathiasson.nu
GPG Fingerprint: A9A7 F8F6 9821 F415 B066 77F1 7FF5 C2E6 7BF2 F228
Peter Makholm
2004-04-16 09:51:41 UTC
Permalink
Post by Eduard Bloch
Post by W. Borgert
Post by Adrian 'Dagurashibanipal' von Bidder
- what's the different between poweroff and halt? They're probably not
both necessary.
AFAIK, halt doesn't switch off the system, poweroff does.
Lol. lrwxrwxrwx 1 root root 4 2004-04-15 09:56 /sbin/poweroff -> halt
You point being?

It is quite normal for programs to bahave differently (most often
different default flags) when called with different names.

According to the manualpage 'poweroff' is more or less equivalent to
'halt -p'.


Just like /bin/{gunzip,gzip,uncompress,zcat} is all hardlinks to the
smae file.
--
Peter Makholm | Why does the entertainment industry wants us to
***@makholm.net | believe that a society base on full surveillance
http://hacking.dk | is bad?
| Do they have something to hide?
Gunnar Wolf
2004-04-15 13:37:14 UTC
Permalink
Post by W. Borgert
for computer literate people, who either are new to Debian or are new to
any UNIXish system, I created a draft "reference card". The card has some
information on how to get help, the dozen most important shell commands,
some apt-get/apt-cache/apt-file and dpkg commands, as well as some more
specialised things. The criteria for me was: Which questions did I get
most often in the last four weeks? Now I like to get feedback, most
(...)
http://people.debian.org/~debacle/refcard.pdf (ISO A4 format)
http://people.debian.org/~debacle/refcard.dbk (DocBook/XML source)
Hi,

Although not a issue with the content, I opened the PDF file using
gv. It appears in two pages (I suppose you meant it for three pages),
and in the second page part of the text appears upside down.

Please contact me when you have the final version ready, I can do the
Spanish translation.

Greetings,
--
Gunnar Wolf - ***@gwolf.cx - (+52-55)5630-9700 ext. 1366
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF
W. Borgert
2004-04-15 14:12:44 UTC
Permalink
Post by Gunnar Wolf
Although not a issue with the content, I opened the PDF file using
gv. It appears in two pages (I suppose you meant it for three pages),
and in the second page part of the text appears upside down.
There should be two pages, three columns each.
I viewed it with xpdf and, eh, acroread.
Post by Gunnar Wolf
Please contact me when you have the final version ready, I can do the
Spanish translation.
That's great, thanks in advance!

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Wouter Verhelst
2004-04-15 12:59:04 UTC
Permalink
On Thu, Apr 15, 2004 at 12:34:56PM +0200, W. Borgert wrote:
[no comments on the contents other than those already given]
Post by W. Borgert
http://people.debian.org/~debacle/refcard.pdf (ISO A4 format)
| Legal Notice
| Permission is granted to copy, distribute and/or modify this document
| under the terms of the GNU Free Documentation License, Version 1.1 or
| any later version published by the Free Software Foundation; with no
| Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.

You are breaking your own license. From
<http://www.gnu.org/licenses/fdl.txt>:

| 2. VERBATIM COPYING
|
| You may copy and distribute the Document in any medium, either
| commercially or noncommercially, provided that this License, the
| copyright notices, and the license notice saying this License applies
| to the Document are reproduced in all copies,

In other words: if you apply the GFDL to your text, you have to include
the text of the GFDL /as part of your work/. I don't see the text of the
GFDL anywhere on your reference card. Not that it would make sense to
actually do this, but according to the letter of the GFDL, you're still
required to do so.

Apart from that, and after long discussion, the GFDL has been deemed not
DFSG-free by the participators of the debian-legal mailinglist. Surely
you wouldn't want to write a reference card about Debian which could not
be distributed by Debian itself?
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
W. Borgert
2004-04-15 14:13:57 UTC
Permalink
Post by Wouter Verhelst
You are breaking your own license. From
I'll change the license to GPL. Thanks!

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Ryan Underwood
2004-04-18 04:54:56 UTC
Permalink
Post by Wouter Verhelst
Apart from that, and after long discussion, the GFDL has been deemed not
DFSG-free by the participators of the debian-legal mailinglist. Surely
you wouldn't want to write a reference card about Debian which could not
be distributed by Debian itself?
Wasn't a GFDL document with "no Front-cover texts and no Invariant
sections" decided to be all right according to the DFSG?
--
Ryan Underwood, <***@icequake.net>
Matthew Palmer
2004-04-18 06:18:05 UTC
Permalink
Post by Ryan Underwood
Post by Wouter Verhelst
Apart from that, and after long discussion, the GFDL has been deemed not
DFSG-free by the participators of the debian-legal mailinglist. Surely
you wouldn't want to write a reference card about Debian which could not
be distributed by Debian itself?
Wasn't a GFDL document with "no Front-cover texts and no Invariant
sections" decided to be all right according to the DFSG?
No. That was the first opinion formed, but further analysis came to the
conclusion that the GFDL had other problems, which caused it to be
non-DFSG-free under any circumstances.

http://people.debian.org/~srivasta/Position_Statement.html

- Matt
Nicolas CANIART
2004-04-15 15:20:33 UTC
Permalink
Post by W. Borgert
Hi,
for computer literate pe
[...]
Post by W. Borgert
1. Please look at the card and point out any errors. Nothing is worse
for a beginner than false information. {"To list your files type
rm -rf /", "Install Mandrake", ...)
I'll do that next week (I'll be on holidays and have a few time for it).
Post by W. Borgert
2. There is still room for your favourite command/config file/whatever.
Tell me - I will add things, until the card is full. Maybe I use one
complete page (1/6 of the card) for the debian-installer (and FAI).
You speak about Databases, Webservers and Corba but is this really usefull
for newbies and isn't too far from Debian, for a Debian specific card ?
And for new to Unix users shouldn't be basic stuffs like 'basis of regex syntax
for shells and grep' good additions to make (when came from windows
to linux world this 'intimidated' me a little) [the *pattern* argument
appears many times on the currently online card]
Post by W. Borgert
3.
Can't help for that sorry.
Post by W. Borgert
4. As soon as the card is complete (or nearly so) and the "English" is
../.. Any volunteers?
I volunteer for a french translation ... interrested ?

Cordially,
Nicolas.
W. Borgert
2004-04-15 16:26:10 UTC
Permalink
Post by Nicolas CANIART
You speak about Databases, Webservers and Corba but is this really usefull
for newbies and isn't too far from Debian, for a Debian specific card ?
In most cases, yes. But I did this card straight from the questions
I got in the last four weeks. The questions were not only about
apt-get, but also about PostgreSQL and omniORB4. Anyway, all table
row already have an id attribute, and I will add id attributes to
the tables, so that an trivial XSL transformation can be used to
extract customised reference cards, if that's needed.
Post by Nicolas CANIART
And for new to Unix users shouldn't be basic stuffs like 'basis of regex syntax
for shells and grep' good additions to make (when came from windows
to linux world this 'intimidated' me a little) [the *pattern* argument
appears many times on the currently online card]
Yes, regexp might be too complex for this little card, but shell
globbing (at least ? and *, maybe [], maybe {}) could find it's place.
Post by Nicolas CANIART
I volunteer for a french translation ... interrested ?
Of course! Many thanks in advance.

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Adrian 'Dagurashibanipal' von Bidder
2004-04-16 07:22:22 UTC
Permalink
[no cc: needed, thanks]
Post by W. Borgert
Post by Nicolas CANIART
You speak about Databases, Webservers and Corba but is this really
usefull for newbies and isn't too far from Debian, for a Debian
specific card ?
In most cases, yes. But I did this card straight from the questions
I got in the last four weeks. The questions were not only about
apt-get, but also about PostgreSQL and omniORB4. Anyway, all table
row already have an id attribute, and I will add id attributes to
the tables, so that an trivial XSL transformation can be used to
extract customised reference cards, if that's needed.
Wow, if you go with that idea, and make it reasonably easy to create
these customized refcards (good documentation, readable makefile, you
know...), this could become more like a 'collection of Linux reference
cards' than just one reference card - especially since I see much
interest by many people in this thread.
Post by W. Borgert
Post by Nicolas CANIART
And for new to Unix users shouldn't be basic stuffs like 'basis of regex syntax
for shells and grep' good additions to make (when came from windows
to linux world this 'intimidated' me a little) [the *pattern*
argument appears many times on the currently online card]
Yes, regexp might be too complex for this little card, but shell
globbing (at least ? and *, maybe [], maybe {}) could find it's place.
I think a regexp section would be very good, but perhaps that's for
later.

The network section: ifup and ifdown are the Debian specific network
configuration commands and should probably be mentioned.

ifup start and stop network interfaces according
ifdown to the configuration in /etc/network/interfaces

cheers
- -- vbi
Nicolas CANIART
2004-04-20 11:56:33 UTC
Permalink
Here is my french translation of the refcard.
I'd suggest few changes :
+ Basic Shell Commands
- Shouldn't be the -? arg add the the -h --help arg.
- Change the 'lists.debian.org' link by the
'www.debian.org/MailingLists/' because it is
+ Translated in various language
+ Contains the debian lists usage policy which is,
IMHO, a *must-read* for new users.
- Change cp description or add -R arg to command synopsis
(cp can't copy dirs without -R option).
+ APT
- Who still uses more ? (keep less only)
- Aptitude but not dselect ? (But i find the last one infinitly
more user friendly !)
- apt-get remove [..] -> Remove packages with all needed packages.
Didn't you mean 'with all [consequenlty|now|any better word]
unneed packages'.

You should also notice that I didn't translate the revision
history. Would you like me to translate it ?
The Above suggestion have, of course, not been applied to the
sent translation.

I also did not translate the sentence :

Run every time, the contents of one of repositories or the file
itself changed.

in APT section cause I don't understand what do you mean.
Could you also put you're make file on-line, I've read the
db2latex stylesheet *-param*.xsl files and found that I have to use the
--string-param latex.babel.language=french
arg. to have the right latex hyphenation and so on but can't find the
options for the paper (a4 lanscape).

Thanks in advance,
Nicolas.
Miles Bader
2004-04-21 01:32:43 UTC
Permalink
Post by Nicolas CANIART
- Aptitude but not dselect ? (But i find the last one infinitly
more user friendly !)
The general consensus seems to be exactly the opposite though.

I think for a refcard aimed at the general public, it makes sense to
list only aptitude.

-Miles
--
`To alcohol! The cause of, and solution to,
all of life's problems' --Homer J. Simpson
Nicolas CANIART
2004-04-21 11:31:32 UTC
Permalink
Post by Miles Bader
Post by Nicolas CANIART
- Aptitude but not dselect ? (But i find the last one infinitly
more user friendly !)
The general consensus seems to be exactly the opposite though.
This, of course, might be very subjective...
Post by Miles Bader
I think for a refcard aimed at the general public, it makes sense to
list only aptitude.
So we could just name it, adding somethinh like : 'see also dselect'

But if you insist I won't obfuscate myself if you don't mention. It was
just a suggestion.

Cordially,
Nicolas.
Miles Bader
2004-04-22 02:11:50 UTC
Permalink
Post by Nicolas CANIART
Post by Miles Bader
Post by Nicolas CANIART
- Aptitude but not dselect ? (But i find the last one infinitly
more user friendly !)
The general consensus seems to be exactly the opposite though.
This, of course, might be very subjective...
Of course; but when I say `general consensus seems', I'm saying that
this is what _most_ people who's opinion I've seen (on debian lists)
have said. There certainly have been people like yourself who strongly
prefer dselect, but they are a distinct minority in my experience.

Morever the people who prefer dselect have usually -- again based on my
overall impression from reading debian mailing lists -- been long-time
users of debian, and so are basically used to and comfortable with
dselect. It sounds like this refcard is intended for exactly the
opposite sort of person, someone who has only a bit of debian
experience.

-Miles
--
[|nurgle|] ddt- demonic? so quake will have an evil kinda setting? one that
will make every christian in the world foamm at the mouth?
[iddt] nurg, that's the goal
Michael Piefel
2004-04-22 08:51:32 UTC
Permalink
Post by Miles Bader
Morever the people who prefer dselect have usually -- again based on my
overall impression from reading debian mailing lists -- been long-time
users of debian, and so are basically used to and comfortable with
dselect.
That would be me. I tried to switch to aptitude twice and returned
twice. I can't even say why.

On the other hand I have two (Debian) newbies here who got used to
dselect very soon. One thing they (and I) have in common is that they
are both vim users. Perhaps that is a kind of conditioning.

Bye,
Mike
--
|=| Michael Piefel
|=| Member of the Debian project
Nicolas CANIART
2004-04-22 14:59:14 UTC
Permalink
Post by Miles Bader
Post by Nicolas CANIART
Post by Miles Bader
Post by Nicolas CANIART
- Aptitude but not dselect ? (But i find the last one infinitly
more user friendly !)
The general consensus seems to be exactly the opposite though.
This, of course, might be very subjective...
Of course; but when I say `general consensus seems', I'm saying that
[blah,blah,blah]
Post by Miles Bader
experience.
Take it easy guy, as a said it was a *just* suggestion !

Cordially,
Nicolas.
W. Borgert
2004-04-16 09:06:04 UTC
Permalink
Hi,

many, many thanks to all of you who sent comments and
suggestions about the reference card. The phrase "the
Debian community is always helpful" in the first section of
reference card proved to be true once again.

NEW URL: http://people.debian.org/~debacle/refcard/
NEW URL: http://people.debian.org/~debacle/refcard/refcard.dbk
NEW URL: http://people.debian.org/~debacle/refcard/refcard.pdf

Now, the card is almost crowded, so I cannot add much more.
Maybe some points about the new installer, e.g. "how and
why to use expert mode", but that's basically it.

If nobody objects, I like to ask for translations.

Gunnar, Nicolas, would you do a Spanish and French
version? Unfortunately, I think I'm unable to provide for a
German translation. I looked at some Debian stuff in
German, but I didn't understand a word. I just don't know
computer-related terms in German - I used English for these
things from the beginning, so I need a volunteer for my own
language :-) An Italian translation would be cool, too!

Question: How are translations of DocBook/XML documents
done? Is there a toolchain similar to gettext? Or do we
have to copy the complete file and translate it separately?
That would be a maintanance nightmare!

Cheers, WB
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
Eduard Bloch
2004-04-16 12:14:13 UTC
Permalink
#include <hallo.h>
Post by W. Borgert
Hi,
many, many thanks to all of you who sent comments and
suggestions about the reference card. The phrase "the
Debian community is always helpful" in the first section of
reference card proved to be true once again.
NEW URL: http://people.debian.org/~debacle/refcard/
NEW URL: http://people.debian.org/~debacle/refcard/refcard.dbk
NEW URL: http://people.debian.org/~debacle/refcard/refcard.pdf
I suggest a little change... Less make-kpkg options, a hint about m-a
instead:

--- refcard.dbk 2004-04-16 14:04:36.000000000 +0200
+++ refcard.dbk.my 2004-04-16 14:03:48.000000000 +0200
@@ -616,15 +616,22 @@
<entry align="left">Call this after installing a new
kernel.</entry>
</row>
- <row id="make-kpkg">
- <entry align="left">make-kpkg <literal>--</literal>initrd
- <literal>--</literal>revision=2:my.1.0
- <literal>--</literal>rootcmd fakeroot
- <literal>--</literal>uc <literal>--</literal>us
- kernel_image</entry>
- <entry align="left">Build a kernel packages from sources,
- if a customised kernel is really needed. Install
- <literal>kernel-package</literal> first.</entry>
+ <row id="make-kpkg">
+ <entry align="left">make-kpkg
+ <literal>--</literal>uc <literal>--</literal>us
+ kernel_image</entry>
+ <entry align="left">Build a kernel packages from sources,
+ if a customised kernel is really needed. Run as root and install
+ <literal>kernel-package</literal> first. Add
+ <literal>--</literal>initrd if the config is based on Debian Sarge
+ kernel. </entry>
+ </row>
+ <row id="m-a">
+ <entry align="left">m-a a-i module
+ kernel_image</entry>
+ <entry align="left">Create and install third-party modules (nvidia,
+ loop-aes). Follow the displayed hints.
+ </entry>
</row>
</tbody>
</tgroup>

Regards,
Eduard.
--
Hoppla, wir leben!
-- Ernst Toller
W. Borgert
2004-04-16 19:28:26 UTC
Permalink
Post by Eduard Bloch
I suggest a little change... Less make-kpkg options, a hint about m-a
I didn't change make-kpkg, because the command line is
exactly the one I use! Every time I use make-kpkg I have to
look in the manual page, just to find out about this command
line. Fortunately, I now have a reference card :-) OTOH, I
don't use make-kpkg anymore, but the kernels by Herbert
exclusively. I added m-a, despite I never used it :-)

Cheers,
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
Alexander Schmehl
2004-04-16 13:32:09 UTC
Permalink
I just don't know computer-related terms in German - I used English
for these things from the beginning, so I need a volunteer for my own
language :-)
On the way, give me a couple of minutes.


Yours sincerely,
Alexander
Jan Kesten
2004-04-16 15:51:43 UTC
Permalink
Post by Alexander Schmehl
On the way, give me a couple of minutes.
Hi all!

Just a bit too slow - but I can look over the german version then -
if you need help, let me know!

Cheers,
Jan
- --

My GnuPG public key is available at ***@the-hidden-relam.de
(autoresonder)

pub 1024D/82201FC4 2003-11-15 Jan Kesten <***@jan-kesten.de>
Primary key fingerprint: 1C10 DC8A F67E 0C2A 781C 2882 BEF9 8290
8220 1FC4
Alexander Schmehl
2004-04-16 16:59:56 UTC
Permalink
Post by W. Borgert
many, many thanks to all of you who sent comments and
suggestions about the reference card.
---
apt-get remove
Remove packages from repository with all needed packages
---

Well, I'm not a native english speaker, but that sounds odd to me. The
packages get removed the site, were I got them? And the packages, needed
for this package are removed, too?

Why not something like:
"Remove installed package, and all depending packages"?


Yours sincerely,
Alexander
Gunnar Wolf
2004-04-16 20:00:15 UTC
Permalink
Post by W. Borgert
(...)
Gunnar, Nicolas, would you do a Spanish and French
version?
Of course - just please wait for me until Monday, at most Tuesday.
Post by W. Borgert
Question: How are translations of DocBook/XML documents
done? Is there a toolchain similar to gettext? Or do we
have to copy the complete file and translate it separately?
That would be a maintanance nightmare!
Why don't you set up refcard as an Alioth project, managed by CVS? We
could do something (albeit simplified, as this is not a vast set of
pages) similar to webwml for Debian's web site translations. And the
'refcard' Alioth project could handle more than just this reference
card - Many, more specialized reference cards for Debian's many
subsystems and even packages - In effect, a refbook :) What do you
think?

Well, back to the webwml point... Translations can mention to which
CVS revision of the original (usually in English) they will point. A
tracker can even be set up, such as
http://www.debian.org/devel/website/stats

Greetings,
--
Gunnar Wolf - ***@gwolf.cx - (+52-55)5630-9700 ext. 1366
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF
W. Borgert
2004-04-16 19:28:18 UTC
Permalink
Post by Gunnar Wolf
Of course - just please wait for me until Monday, at most Tuesday.
Nothing to hurry - I'll need much more time to get stuff
integrated anyway.
Post by Gunnar Wolf
Why don't you set up refcard as an Alioth project, managed by CVS? We
I like to add the refcard to the DDP (Debian documentation
project). They are already in Alioth.
Post by Gunnar Wolf
subsystems and even packages - In effect, a refbook :) What do you
think?
Good idea! There are some areas, where a refcard would be
cool. I hope, that db2latex-xsl will be in unstable soon -
it's needed to create the PDF.

Cheers,
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
Michael Banck
2004-04-17 14:42:38 UTC
Permalink
Post by W. Borgert
many, many thanks to all of you who sent comments and
suggestions about the reference card. The phrase "the
Debian community is always helpful" in the first section of
reference card proved to be true once again.
NEW URL: http://people.debian.org/~debacle/refcard/
NEW URL: http://people.debian.org/~debacle/refcard/refcard.dbk
NEW URL: http://people.debian.org/~debacle/refcard/refcard.pdf
Now, the card is almost crowded, so I cannot add much more.
Maybe some points about the new installer, e.g. "how and
why to use expert mode", but that's basically it.
Uhm, perhaps I'm a bit late, but did you consider adding
'configure-debian' to it? It's a nice debconf'd frontend to
dpkg-reconfigure, so people can choose which package they want to
configure. (It's not easy to tell you have to go 'xserver-xfree86' for a
newbie for example). It's not in stable yet, though.

Indenting multi-line commands would help a bit, too, I guess.


cheers,

Michael
--
Michael Banck
Debian Developer
***@debian.org
http://www.advogato.org/person/mbanck/diary.html
Humberto Massa
2004-04-16 17:51:15 UTC
Permalink
Post by W. Borgert
Hi,
many, many thanks to all of you who sent comments and
suggestions about the reference card. The phrase "the
Debian community is always helpful" in the first section of
reference card proved to be true once again.
Hi. I'm starting a Brazilian Portuguese (pt_BR) translation, but got
kind of busy right now. Probably I will send it to you in the course of
the weekend.
--
br,M
Dave Gudewicz
2004-04-17 18:21:42 UTC
Permalink
The PDF was broken as far as Adobe v6 was concerned and the HTML site was
unavailable at the time of this messge.

Reference card is a good idea. Hope to see it soon.
Gunnar Wolf
2004-04-19 01:34:08 UTC
Permalink
Ummm... I am starting with the Spanish translation. I have a couple of
questions so far:

- About the GPL notice: There are four unofficial translations of the
GPL to Spanish in gnu.org, but no official translation. Should I
leave it then in English? I translated it as well as I could, but of
course, I don't want to be held responsable for a legal mistake
- In the 'Getting help' section:
+ First entry: 'man' does not give 'online help' in the sense many
people understand it - Online is nowadays a synonim to 'in
Internet'. I suggest changing it to 'Read manual page...'
+ When mentioning README.Debian, 'contains specialties' sounds... At
best, ambiguous. Why not 'Debian-specific information'?

I have to go, but expect more :)

Greetings,
--
Gunnar Wolf - ***@gwolf.cx - (+52-55)5630-9700 ext. 1366
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF
Steve Langasek
2004-04-19 02:44:57 UTC
Permalink
Post by Gunnar Wolf
Ummm... I am starting with the Spanish translation. I have a couple of
- About the GPL notice: There are four unofficial translations of the
GPL to Spanish in gnu.org, but no official translation. Should I
leave it then in English? I translated it as well as I could, but of
course, I don't want to be held responsable for a legal mistake
If it is present as the license under which the work is distributed, it
must be left untranslated. AFAIK, the *only* official language of the
GPL is English, as it is very expensive to render a license text into
another language without losing legal nuances.
--
Steve Langasek
postmodern programmer
W. Borgert
2004-04-19 08:12:29 UTC
Permalink
Post by Gunnar Wolf
- About the GPL notice: There are four unofficial translations of the
GPL to Spanish in gnu.org, but no official translation. Should I
leave it then in English? I translated it as well as I could, but of
course, I don't want to be held responsable for a legal mistake
I am not a lawyer - if you really care, ask on -legal,
otherwise I leave it up to you. Maybe you could leave
it in English for now, and translate it into Spanish
later?
Post by Gunnar Wolf
+ First entry: 'man' does not give 'online help' in the sense many
people understand it - Online is nowadays a synonim to 'in
Internet'. I suggest changing it to 'Read manual page...'
Funny. $ man man
...
man - an interface to the on-line reference manuals
...

How about:

Read manual for command, every command and many
configuration files have manual pages, man bash for
builtins.
Post by Gunnar Wolf
+ When mentioning README.Debian, 'contains specialties' sounds... At
best, ambiguous. Why not 'Debian-specific information'?
...odd, yes. I wanted to keep it as short as possible. I
will change that.

Cheers,
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
Harald Dunkel
2004-04-19 14:47:52 UTC
Permalink
Hi WB,

I really appreciate your work on the reference card. But maybe
its allowed to make a suggestion?

Would it be possible to focus on the stuff that is specific to
Debian? Standard Unix tools like cat, man, find, grep, ls, mkdir
etc. are important to know, but they should get their own reference
card (which would be helpfull for all Linux/Unix users, regardless
which distro they are using). Same for Apache, PostgresSQL, and Samba.
This would give you more space on the "Debian GNU/Linux" refcard.



Regards

Harri
W. Borgert
2004-04-19 18:40:38 UTC
Permalink
Post by Harald Dunkel
I really appreciate your work on the reference card. But maybe
its allowed to make a suggestion?
Na klar.
Post by Harald Dunkel
Would it be possible to focus on the stuff that is specific to
Debian? Standard Unix tools like cat, man, find, grep, ls, mkdir
etc. are important to know, but they should get their own reference
card (which would be helpfull for all Linux/Unix users, regardless
which distro they are using). Same for Apache, PostgresSQL, and Samba.
This would give you more space on the "Debian GNU/Linux" refcard.
Ich habe die Reference Card natuerlich mit einer bestimmten
(heterogenen) Nutzergruppe im Kopf erstellt:

1. Kollegen von mir, die bisher ueberwiegend Windows benutzt
haben und benutzen und daher die einfachsten
Shell-Befehle immer wieder vergessen.

2. Andere Kollegen von mir, die Solaris, HP-UX, RedHat, SuSE
oder Mandrake kennen und daher die apt-get- und
dpkg-Befehle nicht im Kopf behalten koennen oder wollen.

Zugegebenermassen sind das zwei Welten, aber trotzdem
Absicht. Danke fuer's Feedback trotzdem!

Cheers,
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
W. Borgert
2004-04-19 18:46:12 UTC
Permalink
Sorry, I forgot that I CCed the list. English translation
Post by W. Borgert
Post by Harald Dunkel
I really appreciate your work on the reference card. But maybe
its allowed to make a suggestion?
Na klar.
en: Of course.
Post by W. Borgert
Post by Harald Dunkel
Would it be possible to focus on the stuff that is specific to
Debian? Standard Unix tools like cat, man, find, grep, ls, mkdir
etc. are important to know, but they should get their own reference
card (which would be helpfull for all Linux/Unix users, regardless
which distro they are using). Same for Apache, PostgresSQL, and Samba.
This would give you more space on the "Debian GNU/Linux" refcard.
Ich habe die Reference Card natuerlich mit einer bestimmten
en: I created the reference with a specific (heterogenous)
user group in mind.
Post by W. Borgert
1. Kollegen von mir, die bisher ueberwiegend Windows benutzt
haben und benutzen und daher die einfachsten
Shell-Befehle immer wieder vergessen.
en: 1. Colleagues of mine, who used (or are using) primarily
Windows and therefore always forget the simplest of
shell commands.
Post by W. Borgert
2. Andere Kollegen von mir, die Solaris, HP-UX, RedHat, SuSE
oder Mandrake kennen und daher die apt-get- und
dpkg-Befehle nicht im Kopf behalten koennen oder wollen.
en: 2: Other colleagues of mine, of know either Solaris, HP-UX,
RedHat, SuSE, or Mandrake and therefore don't (like to)
remember apt-get and dpkg commands.
Post by W. Borgert
Zugegebenermassen sind das zwei Welten, aber trotzdem
Absicht. Danke fuer's Feedback trotzdem!
en: Admittedly that are two worlds, but intention. Thanks
anyway for the Rueckkopplung.

Tschuess,
--
Post by W. Borgert
--
--
W. Borgert <***@debian.org>, http://people.debian.org/~debacle/
Thorsten Roggendorf
2004-04-21 09:16:56 UTC
Permalink
Hi
Post by W. Borgert
I will add sudo.
You have to add visudo too (can be mentioned in the sudo explanation).
/etc/sudoers is best edited with visudo.

Cheers

Thorsten
Thorsten Roggendorf
2004-04-21 10:52:26 UTC
Permalink
Hi

I'm probably a bit late, but I have a few suggestions (the card is great
btw):

- You might want to mention the info command in the Getting Help
section. info can fully replace man, if no info page is found on the
system a manpage will be displayd, but if there is, it's often much more
useful (e.g. info find). info is to man what less is to more. Many
manpages even state that they are outdated and one should consult the
according info-page.

- Speaking of find: You might also want mention locate (and maybe
updatedb, which is related). For searching larger tree structure find is
unpractical especially if you do more than one search. Locate is suited
for simple find tasks and orders of magnitude faster.

- you mention dpkg-reconfigure console-common and ... locales:
mentioning language-env would fit in well there.

- I already mentioned this in another posting to the list, but anyway:
Featuring sudo you might also want to mention visudo. /etc/sudoers is
best edited with visudo if one can handle vi.


There are some things that may not be asked often, but that I would
consider essential for Debian / *nix users to be aware of:

- cron, /etc/crontab
- exim, /var/spool/mail
- dpkg-reconfigure xserver-xfree86
- ~/.bashrc
- /proc, /dev
- init, /etc/rc?.d/*
- /etc/apt/sources.list


Ok, that is all I can currently think of. Obviously it's too much to fit
on the reference card. But maybe you will agree on some issues.

Cheers

Thorsten
Bernd Eckenfels
2004-04-21 11:59:04 UTC
Permalink
Post by Thorsten Roggendorf
Featuring sudo you might also want to mention visudo. /etc/sudoers is
best edited with visudo if one can handle vi.
I realy wonder why it makes such a fuzz to not observe EDITOR and VISUAL. (#164425)


Greetings
Bernd
--
(OO) -- ***@Mörscher_Strasse_8.76185Karlsruhe.de --
( .. ) ecki@{inka.de,linux.de,debian.org} http://www.eckes.org/
o--o 1024D/E383CD7E ***@IRCNet v:+497211603874 f:+497211603875
(O____O) When cryptography is outlawed, bayl bhgynjf jvyy unir cevinpl!
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Josip Rodin
2004-04-21 12:11:07 UTC
Permalink
Post by Thorsten Roggendorf
Featuring sudo you might also want to mention visudo. /etc/sudoers is
best edited with visudo if one can handle vi.
The prefix "vi" in visudo, just like with vipw and vigr, is historical,
one doesn't have to "handle vi" to use it.
--
2. That which causes joy or happiness.
W. Borgert
2004-04-21 12:13:24 UTC
Permalink
Quoting Thorsten Roggendorf <***@uni-bielefeld.de>:
(deletet a lot of good suggestions...)
Post by Thorsten Roggendorf
Ok, that is all I can currently think of. Obviously it's too much to fit
on the reference card. But maybe you will agree on some issues.
I will go through the list when I have time. The most reasonable thing
is to create three refcard variants: user/admin/developer, but I'm not
sure, whether this will be a full time job for me :-)

Thanks for your input, I'll try my best.

Cheers, WB

Btw: At least 50% of the feedback for the refcard is from Germany. Is
my English full of germanisms, so that other people cannot understand?
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Thorsten Roggendorf
2004-04-21 13:00:48 UTC
Permalink
Hi
Post by W. Borgert
Btw: At least 50% of the feedback for the refcard is from Germany. Is
my English full of germanisms, so that other people cannot understand?
There are some, but I think native speakers will still understand most
if not all of the card. Maybe it has something to do with the time zones
or that germans are rather active in Debian, dunno.
Another thing I forgot in the last message: I printed the card on a
professional duplex HP-laser jet. The margins are so small, that part of
the text is cut off. I wonder how many printers will be able to print
that card ...

Cheers

Thorsten
W. Borgert
2004-04-21 14:01:19 UTC
Permalink
Post by Thorsten Roggendorf
Another thing I forgot in the last message: I printed the card on a
professional duplex HP-laser jet. The margins are so small, that part of
the text is cut off. I wonder how many printers will be able to print
that card ...
HP LaserJet 8000 -> perfect.

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Thorsten Roggendorf
2004-04-21 14:24:10 UTC
Permalink
Hi
Post by W. Borgert
HP LaserJet 8000 -> perfect.
Well maybe, but it should be printable on any puny canon inkjet ...

Gruß

Thorsten
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
W. Borgert
2004-04-21 16:41:21 UTC
Permalink
I just wrote a long answer and lost it somehow :-( Again...
Post by Thorsten Roggendorf
Well maybe, but it should be printable on any puny canon inkjet ...
Could you send me the page margins that are OK (in mm/cm)? On my
private HP inkjet the printout sucks anyway :-(

Problem: AFAIK in LaTeX all pages are of the same size. Because of
the already insufficient space on the card, I don't want to make
the margin larger on all pages. If somebody knows, how to tell
LaTeX to have a larger right margin on pages 1 and 4, and a larger
left margin on pages 2 and 5, please educate me!

Questions:

1. Is ISO A4 paper easily available everywhere in the world, esp.
the US? If not, I may have to create a 'letter' variant.

2. How about a CD format (120mm^2 or so?) for including the refcard
on upcoming sarge CDs?

Cheers, WB
--
To UNSUBSCRIBE, email to debian-devel-***@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact ***@lists.debian.org
Gunnar Wolf
2004-04-21 18:29:54 UTC
Permalink
Post by W. Borgert
1. Is ISO A4 paper easily available everywhere in the world, esp.
the US? If not, I may have to create a 'letter' variant.
Nope. In Mexico, I have never seen A4. We only have letter. And I
suppose the same is true for our neighbors.
Post by W. Borgert
2. How about a CD format (120mm^2 or so?) for including the refcard
on upcoming sarge CDs?
Ummm... Sounds nice, but can be _really_ tricky. Anyway, it has been
proven that you are good with TeX.

I will fly ~2hr today, by tomorrow I will send you the translation.

Greetings,
--
Gunnar Wolf - ***@gwolf.cx - (+52-55)5630-9700 ext. 1366
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF
j***@g-tec.co.at
2004-04-22 10:44:10 UTC
Permalink
Post by Thorsten Roggendorf
Hi
Post by W. Borgert
HP LaserJet 8000 -> perfect.
Well maybe, but it should be printable on any puny canon inkjet ...
I also had problems on HP printers. I found out that printing with gv to
a ps file and then printing this ps file works.

greets Jimmy
--
Andreas "Jimmy" Gredler, ***@g-tec.co.at
Get my public key at www.g-tec.co.at
Colin Watson
2004-04-21 13:05:58 UTC
Permalink
Post by Thorsten Roggendorf
I'm probably a bit late, but I have a few suggestions (the card is great
- You might want to mention the info command in the Getting Help
section. info can fully replace man, if no info page is found on the
system a manpage will be displayd, but if there is, it's often much more
useful (e.g. info find). info is to man what less is to more.
Warning: religious issue detected.

FWIW, this isn't true: man -k; man uses your preferred pager while info
has its own built-in (and fairly sucky) one; man can format man pages to
PostScript etc.; I don't see a way to specify a manual section to info;
does info *really* handle non-ASCII encodings better than man currently
does?; and so on.

Manual page viewing is a simple hack in info, but it doesn't replace
man.

Cheers,
--
Colin Watson [***@flatline.org.uk]
Wouter Verhelst
2004-04-21 13:22:14 UTC
Permalink
Post by Colin Watson
Post by Thorsten Roggendorf
I'm probably a bit late, but I have a few suggestions (the card is great
- You might want to mention the info command in the Getting Help
section. info can fully replace man, if no info page is found on the
system a manpage will be displayd, but if there is, it's often much more
useful (e.g. info find). info is to man what less is to more.
Warning: religious issue detected.
Agreed.
Post by Colin Watson
FWIW, this isn't true: man -k; man uses your preferred pager while info
has its own built-in (and fairly sucky) one; man can format man pages to
PostScript etc.; I don't see a way to specify a manual section to info;
does info *really* handle non-ASCII encodings better than man currently
does?; and so on.
Manual page viewing is a simple hack in info, but it doesn't replace
man.
Additionally, info pages tend to be large, bloated, and full of
unnecessary information (at least, information that IMO does not belong
in on-line documentation) whereas manpages usually are concise and
to-the-point documentation; precisely the sort of documentation one
needs when actually working with a computer (as opposed to, say, sitting
in a sofa with your feet in the direction of the fireplace, and a book
in your hands that explains you how a given piece of software works).

Not to mention the fact that Debian Policy mandates software to feature
manpages, which cannot be said about info.

That doesn't mean one wouldn't want to add a reference to info, though;
in many cases when there's an info file, the manpages are outdated,
incomplete, or unexisting. Especially GNU software seems to be horrible
in this regard.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Jan Nieuwenhuizen
2004-04-21 15:30:28 UTC
Permalink
Post by Wouter Verhelst
Additionally, info pages tend to be large, bloated, and full of
unnecessary information
Warning: religious issue detected.
Post by Wouter Verhelst
(at least, information that IMO does not belong in on-line
documentation)
Now you got me wondering, what kind of documentation should be
prohibited from digital distribution, in your opinion?
Post by Wouter Verhelst
Not to mention the fact that Debian Policy mandates software to feature
manpages, which cannot be said about info.
Good point. How about fixing that requirement?
Post by Wouter Verhelst
Especially GNU software seems to be horrible in this regard.
You're trolling, but just to be sure, you do know why GNU deprecated
`man' about 15 years ago?

Jan.
--
Jan Nieuwenhuizen <***@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
Wouter Verhelst
2004-04-21 16:03:23 UTC
Permalink
Post by Colin Watson
Post by Wouter Verhelst
Additionally, info pages tend to be large, bloated, and full of
unnecessary information
Warning: religious issue detected.
Post by Wouter Verhelst
(at least, information that IMO does not belong in on-line
documentation)
Now you got me wondering, what kind of documentation should be
prohibited from digital distribution, in your opinion?
I never said that; I only said that good on-line documentation should
concise and to-the-point information. Full, extensive documentation
should be put in a HOWTO, a book, or on a website -- not in the primary
on-line documentation tool.
Post by Colin Watson
Post by Wouter Verhelst
Not to mention the fact that Debian Policy mandates software to feature
manpages, which cannot be said about info.
Good point. How about fixing that requirement?
How about let's not?

This requirement allows a user to log on to a system, type "man foo",
and get documentation; such consistency is good. Since there's much more
software that has manpages but no texinfo documentation than the other
way around, it's far easier to require manpages than it is to require
texinfo.
Post by Colin Watson
Post by Wouter Verhelst
Especially GNU software seems to be horrible in this regard.
You're trolling, but just to be sure, you do know why GNU deprecated
`man' about 15 years ago?
Well, no. The only reference as to why that I could find is this
paragraph from the GNU coding standards:

``Don't use Unix man pages as a model for how to write GNU documentation;
most of them are terse, badly structured, and give inadequate
explanation of the underlying concepts. (There are, of course, some
exceptions.) Also, Unix man pages use a particular format which is
different from what we use in GNU manuals.''

(section 6.1, at http://www.gnu.org/prep/standards_33.html)

If you have more information, I'm happy to learn about it; but let me
start off by disagreeing with the stance that being "terse" or giving
"inadequate explanation of the underlying concepts" is necessarily a
problem. As I said, IMO on-line documentation should contain concise and
to the point information; underlying concepts, if they're complex, and
other blatter, are for HOWTO's and books (either digitally or printed).
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Chad Walstrom
2004-04-21 16:28:27 UTC
Permalink
Post by Wouter Verhelst
I never said that; I only said that good on-line documentation should
concise and to-the-point information. Full, extensive documentation
should be put in a HOWTO, a book, or on a website -- not in the
primary on-line documentation tool.
"On-line documentation" is not exclusive to manpages. Let's drop the
use of "on-line documentation" entirely when comparing manpages to info
docs. In fact, HOWTO's, books, and other classifications of
documentation CONTENT do not imply the MEDIA in which they are
distributed.

manpages SHOULD be concise and illustrative on how to use a given
application. info DOCS contain documentation of the underlying
principles, verbose examples, and whatever musings the developer
desires. Both are useful in their own right. Both are forms of
"on-line documentation".

texinfo markup is a pain to use unless you use it a lot. The same can
be said for many markup languages. In the opinion of texinfo "people",
it is far easier to write in than nroff. I don't mind taking an
existing manpage as a template and changing the content. It's not
really that difficult.

IMHO, reStructuredText is the easier to use over either nroff or
texinfo. Does that mean it's the Right Thing(tm) for Everything? No.

Every tool has it's place. Debian's mandate is that every application
requires a manpage. It's a good mandate. The Texinfo v.s. man (nroff)
argument has no place in this context.
--
Chad Walstrom <***@wookimus.net> http://www.wookimus.net/
assert(expired(knowledge)); /* core dump */
Jan Nieuwenhuizen
2004-04-21 17:08:45 UTC
Permalink
Post by Wouter Verhelst
I never said that; I only said that good on-line documentation should
concise and to-the-point information. Full, extensive documentation
should be put in a HOWTO, a book, or on a website -- not in the primary
on-line documentation tool.
Why do you want (at least) two documentation tools? I really dislike
having to travel down the path of possible sources of documentation.

In general, I like info pages a lot, I can live with man pages, find
.txt.gz files in /usr/share/doc/* a bit clumsy. But sometimes it gets
worse, and there aro only .html pages or .ps.gz. That's really
annoying because there is no good search function or index.
Post by Wouter Verhelst
This requirement allows a user to log on to a system, type "man foo",
and get documentation; such consistency is good.
Yes, consistency is good. However, I'm quite happy with the the
python info pages, but think that `man perl' is broken beyond repair;
it illustrates why `man 2 open' is fine, but `must have man' does not
guarantee sanity or bring enlightenment.
Post by Wouter Verhelst
Since there's much more software that has manpages but no texinfo
documentation than the other way around, it's far easier to require
manpages than it is to require texinfo.
Yes, that's easier for the developer, but it's a lot less useful for
the user. I prefer better usability, if possible.
Post by Wouter Verhelst
If you have more information, I'm happy to learn about it; let me
start off by disagreeing with the stance that being "terse" or
giving "inadequate explanation of the underlying concepts" is
necessarily a problem.
There's also

In general, a GNU manual should serve both as tutorial and
reference. It should be set up for convenient access to each
topic through Info, and for reading straight through (appendixes
aside). A GNU manual should give a good introduction to a
beginner reading through from the start, and should also provide
all the details that hackers want. The Bison manual is a good
example of this--please take a look at it to see what we mean.

Just for fun, have a look at the bison info pages, and compare that
with the FreeBSD yacc man page, for example.

YACC(1) FreeBSD General Commands Manual YACC(1)

NAME
yacc - an LALR(1) parser generator

SYNOPSIS
yacc [-dlrtv] [-b file_prefix] [-o output_filename] [-p symbol_prefix]
filename

DESCRIPTION
The yacc utility reads the grammar specification in
the file filename and generates an LR(1) parser for it. The
parsers consist of a set of LALR(1) parsing tables and a
driver routine written in the C programming language. The
yacc utility normally writes the parse tables and the driver
routine to the file y.tab.c.

The following options are available:

<SNIP options>

If the environment variable TMPDIR is set, the string denoted
by TMPDIR will be used as the name of the directory where the
temporary files are created.

FILES
y.code.c
y.tab.c
y.tab.h
y.output
/tmp/yacc.aXXXXXXXXXX
/tmp/yacc.tXXXXXXXXXX
/tmp/yacc.uXXXXXXXXXX

DIAGNOSTICS
If there are rules that are never reduced, the number of such
rules is reported on standard error. If there are any
LALR(1) conflicts, the num- ber of conflicts is reported on
standard error.

FreeBSD 4.7 May 24, 1993 FreeBSD 4.7

And that's all documentation there is. Your assignment: write a
simple parser using yacc.
Post by Wouter Verhelst
As I said, IMO on-line documentation should contain concise and to
the point information; underlying concepts, if they're complex, and
other blatter, are for HOWTO's and books (either digitally or
printed).
HOWTOs are often a desperate effort by users to make up for programs
that lack good documentation. We agree about blatter, I think.
Adding words does not necesarily make bad documentation better.

Jan.
--
Jan Nieuwenhuizen <***@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
v***@parcelfarce.linux.theplanet.co.uk
2004-04-21 18:10:52 UTC
Permalink
Post by Jan Nieuwenhuizen
Just for fun, have a look at the bison info pages, and compare that
with the FreeBSD yacc man page, for example.
[snip the manpage in question]
Post by Jan Nieuwenhuizen
And that's all documentation there is. Your assignment: write a
simple parser using yacc.
Bullshit. The manpage in question documents _compiler_, not the language.
BTW, do you really suggest that info gcc is a good (or even realistic) way
to learn C or, better yet, C++?
Jan Nieuwenhuizen
2004-04-21 18:30:29 UTC
Permalink
Post by v***@parcelfarce.linux.theplanet.co.uk
Post by Jan Nieuwenhuizen
And that's all documentation there is. Your assignment: write a
simple parser using yacc.
Bullshit.
The argument was: terse documentation good, underlying concepts bad.
Post by v***@parcelfarce.linux.theplanet.co.uk
The manpage in question documents _compiler_, not the language.
My point exactly! The info pages describe both, which I argue to be
good thing. What would be your preferred stategy to complete the
parser assignment, given nothing but a (Free)BSD system?
Post by v***@parcelfarce.linux.theplanet.co.uk
BTW, do you really suggest that info gcc is a good (or even
realistic) way to learn C or, better yet, C++?
I think it would be a great thing if we had good C and C++ tutorials
available in info. And I think info would be a better choice for such
a tutorial than man.

Jan.
--
Jan Nieuwenhuizen <***@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
v***@parcelfarce.linux.theplanet.co.uk
2004-04-21 18:42:11 UTC
Permalink
Post by Jan Nieuwenhuizen
Post by v***@parcelfarce.linux.theplanet.co.uk
Bullshit.
The argument was: terse documentation good, underlying concepts bad.
No, it wasn't. Both are needed and since they require very different
styles, they'd better not be mixed. One size does *NOT* fit all.
Wouter Verhelst
2004-04-21 19:25:07 UTC
Permalink
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
I never said that; I only said that good on-line documentation should
concise and to-the-point information. Full, extensive documentation
should be put in a HOWTO, a book, or on a website -- not in the primary
on-line documentation tool.
Why do you want (at least) two documentation tools?
Are you suggesting that "foo --help" should contain everything,
including underlying concepts and references to other documentation? If
not, then you, yourself, are also suggesting more than one source of
documentation.

My point is: there are different types of documentation sources for
different purposes. --help output should not try to be complete;
similarly, on-line documentation does not have to contain information on
underlying concepts if they are rather complex.
Post by Jan Nieuwenhuizen
I really dislike having to travel down the path of possible sources of
documentation.
I much prefer different sources of documentation with different
purposes: --help output for answering quick "how was it again" type of
questions; on-line documentation (such as manpages, or on-line help)
documenting options and features; and books, HOWTOs, manpages from
section 7 (although those aren't used that often on (GNU/)Linux), or
other similar things documenting the "bigger picture".

If those purposes get messed up, then having to travel down the path of
possible sources is, indeed, painful; if that's not the case (and I
often find it isn't), there is no problem, and it in fact helps you
(because you don't get information you're not looking for).
Post by Jan Nieuwenhuizen
In general, I like info pages a lot, I can live with man pages,
Well, we disagree here, but that isn't new, right?
Post by Jan Nieuwenhuizen
find .txt.gz files in /usr/share/doc/* a bit clumsy.
It depends.
Post by Jan Nieuwenhuizen
But sometimes it gets worse, and there aro only .html pages or .ps.gz.
That's really annoying because there is no good search function or
index.
Can't agree more here.
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
This requirement allows a user to log on to a system, type "man foo",
and get documentation; such consistency is good.
Yes, consistency is good. However, I'm quite happy with the the
python info pages, but think that `man perl' is broken beyond repair;
I don't really like "man perl" either.
Post by Jan Nieuwenhuizen
it illustrates why `man 2 open' is fine, but `must have man' does not
guarantee sanity or bring enlightenment.
Hm. I never intended to say that; if I have, apologies.

What I meant to say is that, IME, info pages tend to lean towards
over-documentation, so that one does not easily find the documentation
one needs anymore. Since manual pages need to be put everything on one
page, you don't see the same thing there.

I'm not suggesting that all manpages are great, or that all info pages
are crap. What i'm suggesting is that due to the difference in format,
manpages usually contain documentation better suited for on-line
documentation than info pages do.
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
Since there's much more software that has manpages but no texinfo
documentation than the other way around, it's far easier to require
manpages than it is to require texinfo.
Yes, that's easier for the developer, but it's a lot less useful for
the user. I prefer better usability, if possible.
Requiring developers to write extensive info pages on software they want
to package before they get it uploaded will probably result in less
inclination to package software (and, thus, to document them). I assert
that is less useful than having "more useful" documentation, even if I
would agree that info generally is indeed more useful than manpages
(which I don't).
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
If you have more information, I'm happy to learn about it; let me
start off by disagreeing with the stance that being "terse" or
giving "inadequate explanation of the underlying concepts" is
necessarily a problem.
There's also
In general, a GNU manual should serve both as tutorial and
reference. It should be set up for convenient access to each
topic through Info, and for reading straight through (appendixes
aside). A GNU manual should give a good introduction to a
beginner reading through from the start, and should also provide
all the details that hackers want. The Bison manual is a good
example of this--please take a look at it to see what we mean.
Yeah, well, that's braindead.

For a good tutorial, one needs an easy to read text that does not
necessarily document everything, but one that leads the user through the
major concepts of the program, and points out a few interesting features
here and there without going in too much detail. In the name of
simplifying things for the reader, it's no big deal if a tutorial isn't
fully accurate at the beginning, so long as confusion is cleared out
later. It's not necessary to be able to pick just part of the tutorial;
to really make a tutorial useful, one should be able to read it start to
end; and after doing that, one should at least have an understanding of
how the software works.

For a good reference, an easy to read text is not required; rather, good
reference documentation contains every detail on every part of the
software, no matter how unimportant in the bigger picture, and it should
do so without errors or without simplification. It's not necessary for a
good reference manual to have an easy readable text which can be read
start to end; rather, a reference manual should consist of small blocks
of detailed information which can each be read separately, and which
point to related items.

These two types of documentation are so fundamentally different that
it's plainly impossible to make one text which can serve both purposes
well. Documentation which does serve as both a reference manual is
usually split up in a "Part I: Tutorial" and a "Part II: Reference" or
so. This is even the case in the above mentioned bison info pages; the
first page one gets after entering "info bison" clearly contains a
header "Tutorial section" and a header "Reference section". In fact, I
have yet to see the first piece of documentation that does not work like
that, that can be used both as a reference and as a tutorial, and that
is doing both jobs equally well (as opposed to equally bad).

If it's not possible to create one text that can be used for both
purposes; if it is indeed necessary to logically split up your text
anyway so that you effectively have two manuals in one, then why require
them to be part of the same document in the first place? That has quite
a few drawbacks too:
* People that need a tutorial don't always need the reference
documentation (yet), and vice versa; throwing them together and
forcing people to install both of them or none of them isn't really
nice.
* It makes looking for the required information harder. If I'm looking
at a manpage, using less as a pager, and want to find information on
the "--foo" option, I can hit "/--foo" and be fairly sure I end up
with the reference documentation of the "--foo" option. If I do the
same in `info', it is not at all certain whether I will end up with
either the reference documentation or a section of the tutorial that
happens to handle the --foo option (of course, redoing the same search
helps, but the point is that it's necessary to do that in the first
place)
* People that write good reference documentation are not necessary the
same people that write good tutorials. Forcing both types of
documentation to be part of the same source will either end you up
with one person doing all of it, thereby having a good tutorial and a
bad reference (or vice versa), one group working on the tutorial part
with another working on the reference part, resulting in better
documentation but unnecessary coordination; or one group of people
working on "everything" with overall bad documentation as a result.
Post by Jan Nieuwenhuizen
Just for fun, have a look at the bison info pages, and compare that
with the FreeBSD yacc man page, for example.
[...]
Post by Jan Nieuwenhuizen
And that's all documentation there is. Your assignment: write a
simple parser using yacc.
The FreeBSD manual page on yacc isn't meant as a tutorial on writing
LALR parsers, nor is it meant as a reference on the options one can have
while writing a parser. It is meant as on-line documentation for using
the 'yacc' binary from the command line, and does this job well.
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
As I said, IMO on-line documentation should contain concise and to
the point information; underlying concepts, if they're complex, and
other blatter, are for HOWTO's and books (either digitally or printed).
HOWTOs are often a desperate effort by users to make up for programs
that lack good documentation.
True; but since they're usually written by people who do nothing but
play with the software, use it, write down their experiences, and
publish that, there are quite some HOWTOs that are pure beaty. Yes,
there are exceptions.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Jan Nieuwenhuizen
2004-05-03 08:18:14 UTC
Permalink
Post by Wouter Verhelst
Are you suggesting that "foo --help" should contain everything,
No, I must have been unclear. foo --help is OK. Only for the
simplest of programs, foo --help can and should display more than a
fraction of the program's funtionality or documentation.

If you know beforehand that you need to learn more than the name of
the command line switches or where the output goes, it would be good
if there was one source of documentation, not a whole path to follow.
Man is fine for simple things, info is just the next step; it's fine
for both simple and more fleshy documentation. With man, more
information easily gets in the way, that's why man pages are usually
terse, and terse man pages are often considered to be better. Info
solves the need for being terse. More information is not a problem
like it is with man.
Post by Wouter Verhelst
What I meant to say is that, IME, info pages tend to lean towards
over-documentation, so that one does not easily find the documentation
one needs anymore
Info has indexes, menus (and also the poor man's string search and
regex searches). If you cannot find the information you are looking
for very easily in an info document, I consider that to be a bug that
should be reported and fixed.
Post by Wouter Verhelst
Post by Jan Nieuwenhuizen
In general, a GNU manual should serve both as tutorial and
reference.
Yeah, well, that's braindead.
Why do you think that? I think it is a very difficult thing to write,
but the best type of documentation for a user if you do get it right.

The best way to understand why I think it can be done, would be to
read the TeX book, and or the metafont manual by Donald Knuth. They
read as a book, but have a great separation into concepts and a good
index, which makes for an excellent reference.
Post by Wouter Verhelst
If it's not possible to create one text that can be used for both
purposes;
I hope to think this assumption is wrong. It's the easy route to
take, as a documentation writer, but you can do better, imho.

Jan.
--
Jan Nieuwenhuizen <***@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
v***@parcelfarce.linux.theplanet.co.uk
2004-05-03 08:34:19 UTC
Permalink
Post by Jan Nieuwenhuizen
for both simple and more fleshy documentation. With man, more
information easily gets in the way, that's why man pages are usually
terse, and terse man pages are often considered to be better. Info
solves the need for being terse. More information is not a problem
like it is with man.
More information _is_ a problem when you need a quick and terse summary
instead of tutorial and need it with minimal fuss. Saying "oh, but
you don't really want that, you will be much better off with walking
a bunch of hypertext links and we have so much more to say" is only
going to annoy - the need is real and it's a user requirement, not
a program limitation.

Tutorials have their place; so do reference cards. Mixing those is
not a good idea.
Jan Nieuwenhuizen
2004-05-03 08:58:04 UTC
Permalink
Post by v***@parcelfarce.linux.theplanet.co.uk
More information _is_ a problem when you need a quick and terse summary
When it is, it's a good idea, and easy to include a reference card, or
cheat sheet in the (info) documentation. I'm not convinced that the
best way to provide quick access to documentation in a reference card
or cheat-sheet like manner is to provide different types means of
documentation browsers.
Post by v***@parcelfarce.linux.theplanet.co.uk
you will be much better off with walking a bunch of hypertext links
and we have so much more to say
This is really not what I want to advocate. Of course quick and easy
access is good. That's a reason why I think that different possible
sources to hunt for information is not the ideal situation.

The index should bring you where you want to go, that's only one link
away. It should be quicker than string searching. If not, I consider
that to be a bug.
Post by v***@parcelfarce.linux.theplanet.co.uk
Tutorials have their place; so do reference cards. Mixing those is
not a good idea.
Hmm. I think it would be great if every info document had a top-level
menu node called `Quick reference card'.

Jan.
--
Jan Nieuwenhuizen <***@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
Isaac To
2004-05-03 09:03:26 UTC
Permalink
Jan> Hmm. I think it would be great if every info document had a
Jan> top-level menu node called `Quick reference card'.

Indeed it is even better: the info command can be invoked with a "-O" flag.
Indeed, most of the time I think the information that should be given by
"info -O foo" is about the same as that given by "man foo".

Regards,
Isaac.
Jan Nieuwenhuizen
2004-05-03 10:45:53 UTC
Permalink
Post by Isaac To
Jan> Hmm. I think it would be great if every info document had a
Jan> top-level menu node called `Quick reference card'.
Indeed it is even better: the info command can be invoked with a "-O" flag.
I know about the `Invoking Foo' node; that's not what I meant. A list
of command line switches is not the same as a cheat sheet or reference
card.

Also, I find the info reader quite broken, and would not advocate that
too loudly.

Jan.
--
Jan Nieuwenhuizen <***@gnu.org> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien | http://www.lilypond.org
Wouter Verhelst
2004-05-03 13:46:49 UTC
Permalink
Post by Jan Nieuwenhuizen
Post by v***@parcelfarce.linux.theplanet.co.uk
More information _is_ a problem when you need a quick and terse summary
When it is, it's a good idea, and easy to include a reference card, or
cheat sheet in the (info) documentation. I'm not convinced that the
best way to provide quick access to documentation in a reference card
or cheat-sheet like manner is to provide different types means of
documentation browsers.
If that is your problem, then you should use a program like "konqueror",
which allows you to browse both manpages, info pages, websites, and
other sources of documentation.
Post by Jan Nieuwenhuizen
Post by v***@parcelfarce.linux.theplanet.co.uk
you will be much better off with walking a bunch of hypertext links
and we have so much more to say
This is really not what I want to advocate. Of course quick and easy
access is good. That's a reason why I think that different possible
sources to hunt for information is not the ideal situation.
The index should bring you where you want to go, that's only one link
away. It should be quicker than string searching. If not, I consider
that to be a bug.
Searching an index requires a string search, too. Which has to be done
manually, usually (because one doesn't often know what the node is
called, unless one knows the documentation already). If the table of
contents is large, you require some time to manually find the right
link. The alternative would be to split the table of contents in
multiple sections, but then that will require you to iterate the
"search, move cursor, select item" cycle a few times, which often takes
even longer.

A string search is massively faster IMHO.
Post by Jan Nieuwenhuizen
Post by v***@parcelfarce.linux.theplanet.co.uk
Tutorials have their place; so do reference cards. Mixing those is
not a good idea.
Hmm. I think it would be great if every info document had a top-level
menu node called `Quick reference card'.
Yes, but not all of them do. In fact, most of them don't.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Wouter Verhelst
2004-05-03 13:41:13 UTC
Permalink
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
Are you suggesting that "foo --help" should contain everything,
No, I must have been unclear. foo --help is OK. Only for the
simplest of programs, foo --help can and should display more than a
fraction of the program's funtionality or documentation.
If you know beforehand that you need to learn more than the name of
the command line switches or where the output goes, it would be good
if there was one source of documentation, not a whole path to follow.
We disagree then, for reasons you conveniently snipped out.
Post by Jan Nieuwenhuizen
Man is fine for simple things, info is just the next step; it's fine
for both simple and more fleshy documentation. With man, more
information easily gets in the way, that's why man pages are usually
terse, and terse man pages are often considered to be better. Info
solves the need for being terse. More information is not a problem
like it is with man.
IMO, it does not. Many info pages do indeed have an index section, but
many others do not. In some cases, the index section is hard to find. In
many cases, it is incomplete so that when one searches an index section,
it does not yield a result, meaning, you've spent a good few minutes to
find something which will need a full-text search after all anyway.

Also, I don't like doing work which a computer can do more easily for
me. Searching a large index section takes more time than hitting
"/<search term><enter>" and waiting for the result; therefore, it's
silly to do that with on-line documentation.
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
What I meant to say is that, IME, info pages tend to lean towards
over-documentation, so that one does not easily find the documentation
one needs anymore
Info has indexes, menus (and also the poor man's string search and
regex searches). If you cannot find the information you are looking
for very easily in an info document, I consider that to be a bug that
should be reported and fixed.
Well, then in my experience, most -- if not all -- info pages are buggy
by your definition.
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
Post by Jan Nieuwenhuizen
In general, a GNU manual should serve both as tutorial and
reference.
Yeah, well, that's braindead.
Why do you think that?
Uh, I explained that in the part you snipped out.
Post by Jan Nieuwenhuizen
I think it is a very difficult thing to write, but the best type of
documentation for a user if you do get it right.
I've never seen an example where it was "done right".
Post by Jan Nieuwenhuizen
The best way to understand why I think it can be done, would be to
read the TeX book, and or the metafont manual by Donald Knuth.
That could be true; but I've never seen those. Do you have a reference,
so that I an have a look? (I did find
http://www.ctan.org/tex-archive/systems/knuth/tex/texbook.tex by
googling, but that is hardly readable and has been broken on purpose so
that it cannot be converted into something more useful)
Post by Jan Nieuwenhuizen
They read as a book, but have a great separation into concepts and a
good index, which makes for an excellent reference.
Again, this sounds like there are distinct "reference" and "tutorial"
sections. Do correct me if I'm wrong; but if I'm not, I fail to see how
they would be different.
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
If it's not possible to create one text that can be used for both
purposes;
I hope to think this assumption is wrong.
I have yet to see an example which proves you're right.
Post by Jan Nieuwenhuizen
It's the easy route to take, as a documentation writer, but you can do
better, imho.
Given the fact that most developers do not like to write documentation,
taking the easy route is not necessarily a bad idea. It can mean the
difference between "minimal, but sufficient" documentation, and no
documentation at all.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Isaac To
2004-04-22 01:51:34 UTC
Permalink
Wouter> I never said that; I only said that good on-line documentation
Wouter> should concise and to-the-point information. Full, extensive
Wouter> documentation should be put in a HOWTO, a book, or on a website
Wouter> -- not in the primary on-line documentation tool.

As a long time user of Unix and Linux, I find it very useful that HOWTOs and
info are available on-line. Indeed, I never buy any book about Linux, but I
still know a real lot about it. This should never be changed.

Compared to HOWTOs, info files can be navigated much more easily, and is
much more consistent in format. Also, writers of info pages typically make
indices more than those of HOWTOs. Even if authors of HOWTOs make indices,
they are much less useful than info indices as they don't have the amount of
navigation aids as in info. I consider an info page to be much better than
a HOWTO in every regard, except that the developer must spend more effort.

Compared to a book and a web page, info files can be searched in text, which
is hard to be done in a book or a set of web pages in any format (even in
PS). A single page web-site, which would allow searching, is
out-of-question for the long load time and the huge memory it eats up in the
browser (causing it to be slow). Info files are also easier to put into a
distribution and let others find. On the flip side, a web site can contain
graphical information that cannot be easily put on an info file. So they
are approximately on par.

And a book which actually costs money is not affordable (or even available)
for everybody, and even if for you they are, it might be undesirable to pay,
trying a software, find that it is not suitable and repeat.

In any case, I can use info in both a stand-alone info program and within
Emacs, allowing me to use the key bindings that I'm familiar of. This makes
info stand apart from most other tools like the browser, c'os all
alternatives cannot provide the speed of access that I'm used to in info.

Wouter> If you have more information, I'm happy to learn about it; but
Wouter> let me start off by disagreeing with the stance that being
Wouter> "terse" or giving "inadequate explanation of the underlying
Wouter> concepts" is necessarily a problem.

Manuals serve two purposes: for new-comers to learn how to use the programs,
and for users who do not use the program often enough to get the
information. Accordingly there are two sorts of documentations, man pages
and info files. But I'd argue that at many times, the inadequate
explanation is really a problem even for the latter. When I read the man
page of ls, I see the "-l" option described as follows:

-l use a long listing format

Now I use ls -l. What I see are lines like this:

drwx--S--- 2 kkto kkto 48 2003-09-14 14:11 .Trash/

For me, interpreting such lines is now basic instinct. But for first time
users of the option (or even for those who haven't been paying enough
attention to it before), where to know what the "2" and "-rwx--S---" means?
Why there are two "kkto"? A quick on-line documentation should at least
solve such problems. But you can read the man page yourselves to see
whether it satisfies the requirement.

On the other hand, listing all possibilities of ls outputs will make the
manual long and difficult to navigate. There's a point where you really
don't like reading a single page as long as the manpage of bash(1). It
makes much more sense to put such documentations in info format.

Indeed, for the terse documentation, it is easy to just have a short info
page containing the current information of man. If I'm to find something to
unify to, I'll take the same approach as GNU and unify to info.

Regards,
Isaac.
Denis Barbier
2004-04-21 20:55:01 UTC
Permalink
On Wed, Apr 21, 2004 at 05:30:28PM +0200, Jan Nieuwenhuizen wrote:
[...]
Post by Jan Nieuwenhuizen
Post by Wouter Verhelst
Not to mention the fact that Debian Policy mandates software to feature
manpages, which cannot be said about info.
Good point. How about fixing that requirement?
Post by Wouter Verhelst
Especially GNU software seems to be horrible in this regard.
You're trolling, but just to be sure, you do know why GNU deprecated
`man' about 15 years ago?
To make sure that documentation will be available only in English?

Denis
Isaac To
2004-04-23 01:45:16 UTC
Permalink
Colin> FWIW, this isn't true: man -k;

info --apropos

Colin> man uses your preferred pager while info has its own built-in
Colin> (and fairly sucky) one;

The price to pay is that it has no navigation support at all in man: no
cross reference, no parent, and no index. If you don't like Emacs-style
keys in info, there is --vi-keys.

Colin> man can format man pages to PostScript etc.;

TexInfo files can be formatted to PostScript using just plain TeX, just like
man files can be formatted to PostScript using Groff. Of course, formated
.info cannot be formatted to PostScript, just like catman files cannot be
formatted to PostScript.

Colin> I don't see a way to specify a manual section to info;

Try "info 'time(2)'". (Can it be any more intuitive than that?)

Colin> does info *really* handle non-ASCII encodings better than man
Colin> currently does?; and so on.

For this I don't know, though. If this is a problem it should really be
fixed.

Regards,
Isaac.
Colin Watson
2004-04-23 06:33:18 UTC
Permalink
Post by Isaac To
Colin> FWIW, this isn't true: man -k;
info --apropos
That doesn't search man pages; it searches info pages. Not the same
thing at all, and not at all as useful.
Post by Isaac To
Colin> man uses your preferred pager while info has its own built-in
Colin> (and fairly sucky) one;
The price to pay is that it has no navigation support at all in man: no
cross reference, no parent, and no index.
There's w3mman if you're crazy :-)

And you aren't *supposed* to need an index for man pages, beyond what
apropos gives you, nor a parent node. The whole point is that they're
concise reference material. Man pages are a distinct documentation
format with a distinct purpose.
Post by Isaac To
If you don't like Emacs-style keys in info, there is --vi-keys.
Binary toggles aren't nearly as flexible as being able to swap in your
own pager.
Post by Isaac To
Colin> man can format man pages to PostScript etc.;
TexInfo files can be formatted to PostScript using just plain TeX, just like
man files can be formatted to PostScript using Groff. Of course, formated
.info cannot be formatted to PostScript, just like catman files cannot be
formatted to PostScript.
I wasn't arguing about the respective source formats. You said that the
info client can replace man. It can't.
Post by Isaac To
Colin> I don't see a way to specify a manual section to info;
Try "info 'time(2)'". (Can it be any more intuitive than that?)
It could be documented :-)

Actually, the quoting is suboptimal, which is why man has always done it
with 'man 2 time'.
Post by Isaac To
Colin> does info *really* handle non-ASCII encodings better than man
Colin> currently does?; and so on.
For this I don't know, though. If this is a problem it should really be
fixed.
It's no small project.

Cheers,
--
Colin Watson [***@flatline.org.uk]
Isaac To
2004-04-23 15:25:13 UTC
Permalink
Post by Isaac To
For this I don't know, though. If this is a problem it should
really be fixed.
Colin> It's no small project.

Whether it is small or large project it needs to be done---given that in GNU
the standard documentation format is info.

Regards,
Isaac.
Wouter Verhelst
2004-04-23 15:38:10 UTC
Permalink
Post by Isaac To
Post by Isaac To
For this I don't know, though. If this is a problem it should
really be fixed.
Colin> It's no small project.
Whether it is small or large project it needs to be done---given that in GNU
the standard documentation format is info.
We are not GNU. We are Debian, and our standard documentation format is
man. If you think it should be done, please take it up with the right
project.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Colin Watson
2004-04-23 16:52:30 UTC
Permalink
Post by Isaac To
Post by Isaac To
For this I don't know, though. If this is a problem it should
really be fixed.
Colin> It's no small project.
Whether it is small or large project it needs to be done---given that
in GNU the standard documentation format is info.
It may well happen for info pages, but I'll put money on them not
bothering to do it properly for their man page viewing wrapper. As the
man-db and groff maintainer I've been wrestling with this in one way or
another for years, and it's hard.
--
Colin Watson [***@flatline.org.uk]
Manoj Srivastava
2004-04-25 08:22:43 UTC
Permalink
Post by Isaac To
Post by Isaac To
For this I don't know, though. If this is a problem it should
really be fixed.
Colin> It's no small project.
Post by Isaac To
Whether it is small or large project it needs to be done---given
that in GNU the standard documentation format is info.
Uhh -- what? I thought we had decided to standardize on HTML
for extended documentation? I swear I read that somewhere.


12.4. Preferred documentation formats
-------------------------------------

The unification of Debian documentation is being carried out via HTML.

So there. :P

manoj
--
Money may buy friendship but money cannot buy love.
Manoj Srivastava <***@debian.org> <http://www.debian.org/%7Esrivasta/>
1024R/C7261095 print CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Nathanael Nerode
2004-04-23 19:15:11 UTC
Permalink
Post by Thorsten Roggendorf
Hi
I'm probably a bit late, but I have a few suggestions (the card is great
- You might want to mention the info command in the Getting Help
section. info can fully replace man, if no info page is found on the
system a manpage will be displayd, but if there is, it's often much more
useful (e.g. info find). info is to man what less is to more. Many
manpages even state that they are outdated and one should consult the
according info-page.
Emacs-dislikers like me will prefer 'pinfo'. :-)
--
There are none so blind as those who will not see.
Pablo Santiago Blum de Aguiar
2004-04-22 14:52:55 UTC
Permalink
Post by W. Borgert
(...)
4. As soon as the card is complete (or nearly so) and the "English" is
fixed, I will provide a German translation. I am interested in having
the card translated to Italian and other languages. Any volunteers?
(...)
Hi,

I would very like to help and translate the card to Brazilian Portuguese.

Regards,
--
.''`. Pablo Aguiar <***@brfree.com.br>
: :' : Proud Debian GNU/Linux User and Administrator
`. `'` GNU/Linux User #346447 - PC #238975
`- Debian: from the names of its creator, Ian Murdock, and his wife, Debra.

Thu, Apr 22 2004, 11:48:23 GMT - 0300
Loading...