My comments on David Morris's revised manuals
I'll generally quote the diff that I'm reading. I suggest you use
your editor's search feature to find the bits I'm talking about ...
Most of my comments are nits. In general I think you've done a
reasonably good job and there are no egregious blunders.
Thanks,
Ian.
** policy.sgml:
+In summary, this criteria involves
+<list compact>
+<item>
+checking package copyright.
+<item>
`criteria' is the plural of `criterion' (meaning a single condition
which must be fulfilled for some purpose). You mean `these criteria
are'.
+If you are compiling a package with both a shared library version and
+a static library version (when the library is not freely distributable)
+use the <tt/-fPIC/ parameter for the shared library version and without
+the <tt/-fPIC/ parameter for the version with the static library.
Err, `if you are [building both] use [-fPIC] for [one case] and
without [-fPIC] for the [other case]' ? This sentence is malformed.
I don't understand where this requirement came from. When building an
ELF shared library the _library_ must be compiled -fPIC, but the
_applications_ don't need it.
Send the word <tt/subscribe/ in the <em/Subject/ of a mail to
<email/debian-devel-REQUEST@lists.debian.org/. In case of problems
-contact the list administrator, Anders Chrigstrom <email/ac@netg.se/.
+contact the list administrator, Bruce Perens <email/bruce@Pixar.com/.
I think that perhaps this should be <listmaster@debian.org>.
+Due to export restrictions by the United States government some Debian/GNU packages, including PGP, have been moved to an ftp site outside of the United States. You can find the current locations of those packages on
+<ftpsite/ftp.debian.org/ in the
+<ftppath>/pub/debian/README.non-US</> file.
+<p>
There is a line 218 characters long here. ITYSBT :-).
If you live in a country where use of cryptography even for signing is
forbidden then please contact us so we can make special arrangements.
This does not apply in France, where I believe only encryption and not
signing is forbidden.
-
+<p>
<sect>When you have a package to upload
Also, don't put a <p> at the end of a section - it produces an empty
paragraph, which looks odd.
-
+<p>
+Periodically, a listing of packages in need of new maintainers will be
+sent to the <tt>debian-devel</> list. If you wish to take over maintanance
+of any of those packages, or if you can no longer maintain the packages you
+have, or you simply want to know if any one is working on a package, contact
+Sven Rudolph <email/sr1@debian.org/.
That seems fine, but didn't we establish an indirection address for
this ?
** programmer.sgml:
The Debian version of the FSF's GNU hello program is provided as an
-example for people wishing to create Debian packages.
+example for people wishing to create Debian packages. The Debian
+<prgn/debmake/ package is recommended as a very helpful tool to be used in conj
unction with this manual and the Policy Manual in creating
+and maintaining Debian/GNU packages.
<p>
There's another one of these long lines here, and that sentence sounds
rather confused to me. I'll have to take Bruce's word for it that
debmake is worth recommending.
<em>Note that this document is still a draft!</em>
This isn't true any more and should be deleted (also from the policy
manual, if it's still there).
+This is the currently released version of the Debian/GNU Distribution.
+A new version is released approximately every 3 months following a month of
+"code freeze" status where only bug fixes are allowed. Changes will be allowed
+to the <tt/stable/ distribution only in the event of fixing major bugs. When
+changes are made to the <tt/stable/ Distribution, the minor version number is
+increased (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
The distribution is called `Debian GNU/Linux' - note the position of
the slash. If you want to abbreviate it please say just `Debian'.
`Debian/GNU' is politically problematic :-/.
`Changes will be allowed ... only in the event of fixing major bugs'
is not a sentence. `in the event of' is a prepositional phrase and
requires a noun phrase, not a verb. You mean `... only in order to
fix major bugs.'
Also, please use ` ' instead of " "; thanks.
+<tag/<tt/unstable//
+<item>
+This distribution refers to the current <tt/developmental/ part of Debian/GNU.
+One can expect packages in this distribution to change frequently. This is
+where many bugs and packaging problems are identified, download from this
+distribution at your own risk. There is little restriction on package changes
+in this distribution. New packages and new upstream versions of packages
+receive the <tt/unstable/ or <tt/experimental/ value.
Use `;' or `.' to separate sentences, not `,'. Ie, `... where many
bugs ... are identified; download from this ...'.
The ordering in this paragraph seems confused to me. Perhaps you
should decide what information you want to give for each distribution
value and then give that information in the same order in each
paragraph. I'd suggest: general description; restrictions on changes;
comments on use; other comments.
You mean `new ... packages go into <tt/unstable/ or
<tt/experimental/' rather than that they `receive' anything.
+<tag/<tt/frozen//
+<item>
+From time to time, (every 3 months) the <tt/unstable/ distribution will enter
+a state of "code-freeze" in anticipation of release as a <tt/stable/
+distribution. During this period of testing (usually 4 weeks) only bug fixes
+will be allowed to the <tt/frozen/ distribution. Upstream package changes and
+new packages must go into the <tt/unstable/ distribution.
Also, wrong kind of quotes again.
+<!--
+ Paragraph added per Bug #5299, Guy Maor
+ -->
+Thirdly, the development package should contain a symlink for the
+shared library without a version number. For example, the
+libgdbm1-dev package should include a symlink from /usr/lib/libgdm.so
+to libgdm.so.1.7.3. This symlink is needed by ld when compiling
+packages as it will only look for libgdm.so and libgdm.a when
+compiling dynamically or statically, respectively.
+<p>
You need to add some character markup around the filenames in this
paragraph.
+< !-- moved from section 2.2 , DAM -->
+
+<sect id="shlibs">The <tt/shlibs/ File Format
+<p>
+This file is intended to tell others about the libraries your package provides
+and is required when you provide any shared libraries.
+<p>
It's intended for use by dpkg-shlibdeps. How about `this files are
for use by dpkg-shlibdeps and is required when ...' ?
+<sect>Further Technical information on <tt/shlibs/</>
...
+NOTE from DAM, editor: This section is still in draft form, provided by Heiko
+Schlettermann. I am in the process of cleaning it up, but wanted to get this
+out for comments as soon as possible (meaning before I sleep). Please comment
+on this section as well.
You probably want to remove this at some point :-).
Also, you can use <em/.../ instead of SHOUTING. This is true of the
whole section, which is generally missing tags for <em/.../, <tt/.../,
<list>, &c.
The English in this section is not ideal, but it is comprehensible.
+<p>
+
+<sect1>HOW does <prgn/dpkg-shlibdeps/ work?
<p> at end of section again.
+<prgn/dpkg-shlibdeps/ calls <prgn/ldd/ to determine the shared library names
+ of the files passed on its command line. Currently only binaries
+ (read executables, no libraries) are supported.
I thought that it now worked with shared libraries too ?
+<example>
+* /etc/dpkg/shlibs.default - the maintainer of dpkg
+* /var/lib/dpkg/info/*.shlibs - the maintainer of the * package
+* /etc/dpkg/shlibs.override - the local system administrator (?)
+* */debian/shlibs.local - the maintainer of the * package
+</example>
The shlibs.default file is managed by both dpkg and the local admin
(though they usually don't need to edit this file). The entires in
shlibs.default that are provided by dpkg are just there to fix things
until the shared library packages all have shlibs files.
+<example>
+ dpkg-shlibdeps debian/tmp/usr/{bin,sbin}/*
+</example>
All the examples in this section are indented like this. Don't do
this - the indenting will show up in the output, but the output is
already indented appropriately. The text is indented too and doesn't
need to be but this is less important.
+A real life example:
+<p>
+ Assuming a binary `dclock':
+<p>
YM <tt/dclock/ HTH.
+ $ dpkg-shlibdeps -o dclock
+ dpkg-shlibdeps: warning: unable to find dependency information
+ for shared library libqt
+ (soname 1, path /usr/X11R6/lib/libqt.so.1.0, dependency field Depends)
Can you pick an example not involving Qt ? Just a pet hate of mine ...
--
Ian Jackson, at home. ian@chiark.greenend.org.uk + 44 1223 3 31579
General: ijackson@chiark.greenend.org.uk Permanent: ijackson@gnu.ai.mit.edu
Churchill College, Cambridge, CB3 0DS. http://www.cl.cam.ac.uk/users/iwj10/
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: