Bug#321635: acknowledged by developer (date add example for unix timestamps)
On Tue, Nov 15, 2005 at 09:42:59AM -0700, Bob Proulx wrote: Enrico Zini wrote: I don't think that one more one-line example would make the manpage unreadable. For you it is a single line example. For the other person it is a single line example. For any particular person it is not a problem. But for everyone it is a single line example. After you add one example for everyone the manpage is then unreadable. I've never heard anyone complaining about a manpage being unreadable because it has too many _examples_. I've heard people complaining about manpages having too little examples, though. Plus, we are talking about a manpage which has no examples at all. You must be kidding me. If the main information is kept on info, then the manpage could really be made into a quick-reference sheet. No explanations (refers to Info for that) and quick summary of commandline options and format sequences (as we have now), plus a bunch of one-line useful examples. That is mostly the way things are now. The man pages are generated automatically with 'help2man' from the --help output. This keeps the man page up to date with the program. If the problem is that you don't control the contents of the manpage because it's automatically generated by help2man, please tell it right away without trying to convince me I'm asking something unreasonable. Now, if the problem is help2man, then I wouldn't solve it by asking upstream to adding examples to date --help (which would indeed mess up even more the already verbose output), but to use help2man --include. You can save this file as debian/date.examples, then run help2man as: help2man --include debian/date.examples date and help2man will include the section in the generated manpage. -- [EXAMPLES] .nf # Print the date of two days ago date --date ´2 days ago´ # Print the name of the weekday of Christmas in this year date --date ´25 Dec´ +%j # Print the current day in a format that includes the complete name of the # month, and the weekday date ´+%B %d´ # Print the same, without the padding with zeros (1 instead of 01) date -d 1-may ´+%B %-d´ # Print the current date as unix timestamp date +%s # Parse a unix timestamp date -d @1123341579 .fi -- Ciao, Enrico -- GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini [EMAIL PROTECTED] signature.asc Description: Digital signature
Bug#321635: acknowledged by developer (date add example for unix timestamps)
Enrico Zini wrote: There is quite a bit of language about unix times in the info docs. The date command is complicated enough that you pretty much can't avoid reading the full info about it; I don't see a practical way of adding all the nifty features onto the manpage and still have it readable. Agreed. I don't think that one more one-line example would make the manpage unreadable. For you it is a single line example. For the other person it is a single line example. For any particular person it is not a problem. But for everyone it is a single line example. After you add one example for everyone the manpage is then unreadable. If the main information is kept on info, then the manpage could really be made into a quick-reference sheet. No explanations (refers to Info for that) and quick summary of commandline options and format sequences (as we have now), plus a bunch of one-line useful examples. That is mostly the way things are now. The man pages are generated automatically with 'help2man' from the --help output. This keeps the man page up to date with the program. I'm personally a fan of collecting examples, and I find manpages with examples so much more useful than manpages with just lengthy explanations. Best effects are acheived if useful ones are collected over time. Patches to the documentation sent to the upstream bug reporting address are always apprecated. Since this is something that is better handled upstream it is better to discuss the issue there. Then the entire team can help and comment. bug-coreutils@gnu.org Bob signature.asc Description: Digital signature
Bug#321635: acknowledged by developer (date add example for unix timestamps)
On Sun, Nov 13, 2005 at 10:33:15AM -0800, Debian Bug Tracking System wrote: There is quite a bit of language about unix times in the info docs. The date command is complicated enough that you pretty much can't avoid reading the full info about it; I don't see a practical way of adding all the nifty features onto the manpage and still have it readable. FYI, date currently supports date -d '@1123341579' to avoid the date -d '01/01/1970 1123341579 seconds GMT' construct. I don't think that one more one-line example would make the manpage unreadable. Actually, where did the examples go in the original manpage? There are examples in the italian translation, but not in the LANG=C one. If the main information is kept on info, then the manpage could really be made into a quick-reference sheet. No explanations (refers to Info for that) and quick summary of commandline options and format sequences (as we have now), plus a bunch of one-line useful examples. I'm personally a fan of collecting examples, and I find manpages with examples so much more useful than manpages with just lengthy explanations. Best effects are acheived if useful ones are collected over time. Here's my previous patch to add an EXAMPLES section, integrated with the examples recovered from the (old?) Italian translation and retranslated: --- date.1 2005-08-06 17:32:59.0 +0200 +++ date.1.enrico 2005-08-06 17:34:59.720187776 +0200 @@ -178,6 +178,14 @@ .IP `-' (hyphen) do not pad the field `_' (underscore) pad the field with spaces +.SH EXAMPLES +.nf + # Print the date of two days ago + date --date ´2 days ago´ + + # Print the name of the weekday of Christmas in this year + date --date ´25 Dec´ +%j + + # Print the current day in a format that includes the complete name of the + # month, and the weekday + date ´+%B %d´ + + # Print the same, without the padding with zeros (1 instead of 01) + date -d 1-may ´+%B %-d´ + + # Print the current date as unix timestamp + date +%s + + # Parse a unix timestamp + date -d @1123341579 +.fi .SH AUTHOR Written by David MacKenzie. .SH REPORTING BUGS Do what you want with it: I'm not reopening the bug and I won't insist more than this. Ciao, Enrico -- GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini [EMAIL PROTECTED] signature.asc Description: Digital signature
