Re: Bug#167422: files in /usr/share should be world-readable
On Sat, Nov 09, 2002 at 08:10:02PM -0600, Manoj Srivastava wrote: You can decide not to log for _your_ package. I certainly am going to continue to log the compilation for mine. Well, will you consider placing them in a more FHS-friendly location than /usr/share? :) -- G. Branden Robinson| Suffer before God and ye shall be Debian GNU/Linux | redeemed. God loves us, so He [EMAIL PROTECTED] | makes us suffer Christianity. http://people.debian.org/~branden/ | -- Aaron Dunsmore pgp7NBHqSmGay.pgp Description: PGP signature
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
hi, On Tue, Nov 12, 2002 at 12:12:09PM +, Colin Watson wrote: On Tue, Nov 12, 2002 at 12:58:55PM +0100, Othmar Pasteka wrote: On Wed, Oct 30, 2002 at 04:26:02PM +, Colin Watson wrote: --- policy.sgml.orig 2002-10-30 16:13:24.0 + +++ policy.sgml 2002-10-30 16:14:13.0 + @@ -7476,22 +7476,22 @@ [snip] + There must be a manual page at least for every program. If you probably edited the wrong document, this should be should :). or did I miss something? Yes, you missed this: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=39830msg=75 I didn't miss that. I would love to see seconds to, or discussions of, my most recent proposed diff: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=39830msg=81 this is the updated version where you removed the TODO.Debian paragraph. and in this you have the must which I thought should be a should according to the previous diff you sent. and just afterwards you removed the TODO bit, hence it's a bit confusing. Chris Waters said he would renew his second if I changed must to should, which I did. There have been several seconds to Roland's original proposal. Beyond that, the discussion period I proposed expires very soon! yeah, I'ld second this one with s/must/should/. clear now what i mean? so long Othmar
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
On Tue, Nov 12, 2002 at 01:46:16PM +0100, Othmar Pasteka wrote: On Tue, Nov 12, 2002 at 12:12:09PM +, Colin Watson wrote: On Tue, Nov 12, 2002 at 12:58:55PM +0100, Othmar Pasteka wrote: you probably edited the wrong document, this should be should :). or did I miss something? Yes, you missed this: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=39830msg=75 I didn't miss that. I would love to see seconds to, or discussions of, my most recent proposed diff: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=39830msg=81 this is the updated version where you removed the TODO.Debian paragraph. and in this you have the must which I thought should be a should according to the previous diff you sent. and just afterwards you removed the TODO bit, hence it's a bit confusing. Er, um, oops. :) Thank you for spotting that. --- policy.sgml.orig2002-11-12 12:50:40.0 + +++ policy.sgml 2002-11-12 12:51:30.0 + @@ -7485,22 +7485,22 @@ page included as well. /p - p - If no manual page is available for a particular program, - utility, function or configuration file and this is reported - as a bug to the Debian Bug Tracking System, a symbolic link - from the requested manual page to the manref - name=undocumented section=7 manual page may be - provided. This symbolic link can be created from - filedebian/rules/file like this: - example compact=compact -ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/share/man/man[1-9]/varrequested_manpage/var.[1-9].gz - /example - This manpage claims that the lack of a manpage has been - reported as a bug, so you may only do this if it really has - (you can report it yourself, if you like). Do not close the - bug report until a proper manpage is available./p +p + There should be a manual page at least for every program. If + no manual page is available, this is considered as a bug and + should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + himself, too). Do not close the bug report until a proper + manpage is available.footnote + p + It is not very hard to write a man page. See the url + id=http://www.schweikhardt.net/man_page_howto.html; + name=Man-Page-HOWTO, ttman(7)/tt, the examples + created by ttdebmake/tt or ttdh_make/tt, or the + directory file/usr/share/doc/man-db/examples/file. + /p + /footnote + /p p You may forward a complaint about a missing manpage to the -- Colin Watson [EMAIL PROTECTED]
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi, I second the diff in: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=39830msg=108 - -- James -BEGIN PGP SIGNATURE- Version: GnuPG v1.0.6 (GNU/Linux) Comment: Processed by Mailcrypt 3.5.6 http://mailcrypt.sourceforge.net/ iEYEARECAAYFAj3RAU8ACgkQgD/uEicUG7BmXgCaA9sqMV1YwHpsAvz2l9JsfAwg TlsAoOWgMwWh0+EgY66cDvnFFubN3Pf/ =t2bx -END PGP SIGNATURE-
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
On Tue, 12 Nov 2002, Colin Watson wrote: --- policy.sgml.orig 2002-11-12 12:50:40.0 + +++ policy.sgml 2002-11-12 12:51:30.0 + @@ -7485,22 +7485,22 @@ page included as well. /p - p - If no manual page is available for a particular program, - utility, function or configuration file and this is reported - as a bug to the Debian Bug Tracking System, a symbolic link - from the requested manual page to the manref - name=undocumented section=7 manual page may be - provided. This symbolic link can be created from - filedebian/rules/file like this: - example compact=compact -ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/share/man/man[1-9]/varrequested_manpage/var.[1-9].gz - /example - This manpage claims that the lack of a manpage has been - reported as a bug, so you may only do this if it really has - (you can report it yourself, if you like). Do not close the - bug report until a proper manpage is available./p +p + There should be a manual page at least for every program. If + no manual page is available, this is considered as a bug and + should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + himself, too). Do not close the bug report until a proper + manpage is available.footnote + p + It is not very hard to write a man page. See the url + id=http://www.schweikhardt.net/man_page_howto.html; + name=Man-Page-HOWTO, ttman(7)/tt, the examples + created by ttdebmake/tt or ttdh_make/tt, or the + directory file/usr/share/doc/man-db/examples/file. + /p + /footnote + /p p You may forward a complaint about a missing manpage to the Yes, undocumented(7) needs to die. Seconded. yours, peter -- PGP signed and encrypted | .''`. ** Debian GNU/Linux ** messages preferred.| : :' : The universal | `. `' Operating System http://www.palfrader.org/ | `-http://www.debian.org/ pgpdenIILRqHA.pgp Description: PGP signature
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
I second the proposal in [EMAIL PROTECTED]. -- G. Branden Robinson|You can have my PGP passphrase when Debian GNU/Linux |you pry it from my cold, dead [EMAIL PROTECTED] |brain. http://people.debian.org/~branden/ |-- Adam Thornton pgpzFL2o2b5a8.pgp Description: PGP signature
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
On Tue, Nov 12, 2002 at 05:27:50PM +0100, Josip Rodin wrote: On Tue, Nov 12, 2002 at 12:53:35PM +, Colin Watson wrote: + There should be a manual page at least for every program. If + no manual page is available, this is considered as a bug and + should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + himself, too). Do not close the bug report until a proper + manpage is available.footnote This wording is unclear, it could be misinterpreted by newbie maintainers to mean no manual page at all in the package, as opposed to no manual page per each shipped program. Yeah, I know, I'm nitpicking. :) No manual page is just an abbreviation for what's in the previous sentence. But I don't mind if a policy editor wants to clarify the wording. Note that I don't want to second this proposal even if you fix the above, because I think the undocumented(7) manual page is better than nothing for total newbies. Sorry. :) (Thanks for not outlawing it -- then I'd have to object.) The undocumented(7) page itself can continue to exist. As discussed on IRC, I'm happy to hack man-db so that it can (configurably) point to further information in addition to the No manual entry for foo message. The reason why I'm supporting this proposal is because I find the symlinks to undocumented(7) technically less than ideal in a number of ways. They lead to a farm of dangling symlinks on machines that don't have the manpages package installed (#32019, #53214); they have translation issues that would necessitate some very ugly hacks like not honouring symlinks in the expected way (#167291); and they cause this very common complaint due to the symlinks showing up in 'dpkg -L' output: 17:06 weasel you are happy that you finally found some docs, wait for groff to render it, and what you get is a stupid undocumented(7) page Indeed it is useful to have better-than-nothing documentation for newbies, so let's arrange for the pointer to be kept in a central place, something like: No manual entry for foo. Either you mistyped, or there is no documentation for this feature: try 'man 7 undocumented'. This policy proposal, however, doesn't mandate any particular arrangement along these lines: if you'd be happy with *something* like this in place of the symlink farm then we can sort out the details as time goes on. As you correctly note, I'd simply like to drop the policy *requirement* that programs without a man page ship a symlink to undocumented(7). + It is not very hard to write a man page. See the url + id=http://www.schweikhardt.net/man_page_howto.html; + name=Man-Page-HOWTO, ttman(7)/tt, the examples + created by ttdebmake/tt or ttdh_make/tt, or the + directory file/usr/share/doc/man-db/examples/file. Oh, and that should be manref name=man section=7. Again, I'm happy to leave it to a policy editor to fix the markup if desired. Cheers, -- Colin Watson [EMAIL PROTECTED]
Re: Bug#168761: Documentation is quite messy.
Luca - De Whiskey's - De Vitis wrote:
Debconf documentation is quite messy, or not moslty clear. I'll give you some
examples of inconsistency i've foung between debconf_specification and
debconf-devel(8)
* debconf_specification lists type `text' as available while debconf-devel
does not: none of them seems to assert it's the authoritative source of
documentation.
This is because the text data-type is kind of unused and ill-supported
and deprecated. I have added a mention of it anyway.
The debconf specification is, as its title might suggest, authoratative.
The debconf-devel(7) man page is descriptive. And yes, it does refer
readers to the debconf specification for definitive docs, in at least 3
places.
* neither debconf_specification nor debconf-devel(8) explicitly says that the
Choices: field may include variables, but the example in debconf-devel(8)
use this approach (ADVANCED PROGRAMING WITH DEBCONF - Choosing among
related packages)
This is mildly deprecated, and will be replaced with a better mechanism
in the future, if I can ever get anything through the policy process.
* debconf_specification does not says anything about localization and fields
name while debconf-devel(8) does.
* More over, debconf-devel(8) does not speak about translated fields name
like Description{-ll{_LL}} or Choices{-ll{_LL}}: you need to visit
http://www.debian.org/intl/l10n/templates/hints to know anithing about
this (ony about Description field.
* debconf-devel(8) sugests to use po-debconf package, while
http://www.debian.org/intl/l10n/templates/hints still suggests the
`traditional' way.
I recently removed most of the details from debconf-devel(7) (which does
mention -ll fields still), since the internals of how the fields are
named is all handed by po-debconf now, like the man page says.
Probably this bug should be cloned for debian-policy and debian-www.
I suggests that 2 or 3 people to take the debconf documentation and start
reorganizing it: i would be nicely one of these people.
Randolph Chung was planning at OLS to rewrite the debconf specifcation
into something that is understandable and up-to-date, but he has not
doing any work that I am aware of. There is my policy proposal #160776,
which I think hits most of the points you mentioned above BTW. That has
had two seconds in mid-september, but for some reason has not gotten
into recent releases of policy.
I suggest that:
* debconf-devel(8) should drop the section `THE TEMPLATES FILE', `THE CONFIG
SCRIPT' and `THE DEBCONF PROTOCOL': these issues should be handled by the
debconf_specification only which _must_ be the authoritative source.
debconf-devel(7) is there to be a single source that a package
maintainer should be able to read to learn pretty much everything they
need to know to use debconf. As such its descriptions of the debconf
protocol and templates file and config script are very important. Each
of these sections contains a lot of information and answers to FAQs that
will never get into the policy document. I will not be removing them. I
don't expect that keeping the few bits that overlap with the spec in
sync will be a big deal, since I have to update debconf's code anyway if
the spec changes.
* debconf_specification _must_ be updated acordingly.
* debconf-devel(8) should redirect to proper man pages keeping its content as
small as possible. It's my opinon that this man page should only speack
about
hints and hacks developing with debconf.
I disagree. It's much nicer to have a single page that I can refer
developers to, and which can be read right though or used as a reference
than it is to have the docs scattered amoung many pages. I have gotten
many fewer repeated FAQs from developers about debconf since I wrote the
single large man page.
--
see shy jo
pgpnuGokd9Wbx.pgp
Description: PGP signature
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
[repost, in case the seconds should be signed. they probably should. if so, stating that somewhere in the developer corner would be great. or did I miss something?] hi, On Tue, Nov 12, 2002 at 12:53:35PM +, Colin Watson wrote: --- policy.sgml.orig 2002-11-12 12:50:40.0 + +++ policy.sgml 2002-11-12 12:51:30.0 + @@ -7485,22 +7485,22 @@ page included as well. /p - p - If no manual page is available for a particular program, - utility, function or configuration file and this is reported - as a bug to the Debian Bug Tracking System, a symbolic link - from the requested manual page to the manref - name=undocumented section=7 manual page may be - provided. This symbolic link can be created from - filedebian/rules/file like this: - example compact=compact -ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/share/man/man[1-9]/varrequested_manpage/var.[1-9].gz - /example - This manpage claims that the lack of a manpage has been - reported as a bug, so you may only do this if it really has - (you can report it yourself, if you like). Do not close the - bug report until a proper manpage is available./p +p + There should be a manual page at least for every program. If + no manual page is available, this is considered as a bug and + should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + himself, too). Do not close the bug report until a proper + manpage is available.footnote + p + It is not very hard to write a man page. See the url + id=http://www.schweikhardt.net/man_page_howto.html; + name=Man-Page-HOWTO, ttman(7)/tt, the examples + created by ttdebmake/tt or ttdh_make/tt, or the + directory file/usr/share/doc/man-db/examples/file. + /p + /footnote + /p p You may forward a complaint about a missing manpage to the I second this :). so long Othmar pgpvjxXsVXPHa.pgp Description: PGP signature
Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
On Tue, Nov 12, 2002 at 12:53:35PM +, Colin Watson wrote: Er, um, oops. :) Thank you for spotting that. --- policy.sgml.orig 2002-11-12 12:50:40.0 + +++ policy.sgml 2002-11-12 12:51:30.0 + @@ -7485,22 +7485,22 @@ page included as well. /p - p - If no manual page is available for a particular program, - utility, function or configuration file and this is reported - as a bug to the Debian Bug Tracking System, a symbolic link - from the requested manual page to the manref - name=undocumented section=7 manual page may be - provided. This symbolic link can be created from - filedebian/rules/file like this: - example compact=compact -ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/share/man/man[1-9]/varrequested_manpage/var.[1-9].gz - /example - This manpage claims that the lack of a manpage has been - reported as a bug, so you may only do this if it really has - (you can report it yourself, if you like). Do not close the - bug report until a proper manpage is available./p +p + There should be a manual page at least for every program. If + no manual page is available, this is considered as a bug and + should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + himself, too). Do not close the bug report until a proper + manpage is available.footnote + p + It is not very hard to write a man page. See the url + id=http://www.schweikhardt.net/man_page_howto.html; + name=Man-Page-HOWTO, ttman(7)/tt, the examples + created by ttdebmake/tt or ttdh_make/tt, or the + directory file/usr/share/doc/man-db/examples/file. + /p + /footnote + /p p You may forward a complaint about a missing manpage to the This version gets my second, as promised. cheers -- Chris Waters | Pneumonoultra-osis is too long [EMAIL PROTECTED] | microscopicsilico-to fit into a single or [EMAIL PROTECTED] | volcaniconi- standalone haiku pgpF2IO7Dj11W.pgp Description: PGP signature
New additions to the policy editors set
Hi folks, We have a couple of volunteers for the policy editors set (we need more people on that list, to work through the backlog and alleviate them in the future when any one of us is busy). Branden Robinson [EMAIL PROTECTED], and Josip Rodin [EMAIL PROTECTED] have graciously volunteered to help with the process, and should soon be set up with CVS write privileges. manoj -- The more they over-think the plumbing the easier it is to stop up the drain. Manoj Srivastava [EMAIL PROTECTED] 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
