Bug#634192: Section is suggested explaining the debian/symbols file

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Innocent De Marchi wrote:

> I think it would be nice to add a section for packaging libraryes
> (explaining the use of the debian/symbols).

Documenting the format of the symbols control file (i.e.,
dpkg-gensymbols output) in policy sounds like a good idea indeed.
Currently section 8.1 "Run-time shared libraries" says:

	Correct versioning of dependencies on the newer shared library
	by binaries that use the new interfaces is handled via the
	shlibs system or via symbols files (see deb-symbols(5)).

which hints at two things:

 1. A good place for this information would be a new section 8.7
    after 8.6 "the shlibs system"
 2. You can probably steal some text (or at least information) from
    the deb-symbols(5) manpage.

Documenting the debian/symbols format (i.e., dpkg-gensymbols input) in
policy might also be interesting, but that would be a more difficult
task since the format keeps getting extended.  Besides, I think it's
okay if some odd packages want to generate symbols files some other
way instead of using the dpkg-gensymbols tool.  It is tempting to
continue to let the dpkg-gensymbols(1) manpage be the only
authoritative description of its interface.

Thoughts?  Suggested text?

Thanks,
Jonathan