Re: (docbook-tools) Re: Playing with the spec

[Jorge Godoy <godoy@conectiva.com.br>]

On Tue, Mar 07, 2000 at 11:47:25AM -0600, Manoj Srivastava wrote:
> Hi,
> 
>         This has gotten longer than it should have been, but I am
>  trying to address the issues raisesd in this post, and follow up with
>  some observations on the scope of this standard.

I agree with you. This will be my last post to this list (lsb). Anyone
wanting to discuss this is more than welcome at the
docbook-tools@bazar.conectiva.com.br (to subscribe send a message to
docbook-tools-subscribe@bazar.conectiva.com.br and reply to the
confirmation message). 

> >>"Jorge" == Jorge Godoy <godoy@conectiva.com.br> writes:
> 
>  Jorge> On Mon, Mar 06, 2000 at 09:22:34PM -0600, Manoj Srivastava wrote:
>  >> 
>  >> The package puts it's documentation in /usr/share/doc/foo, and
>  >> the dtd's and files go into /usr/share/foo (note: No version
>  >> number). The postinstallation script copies the DTD into
>  >> /usr/share/sgml/dtd/foo-3.2.dtd; the stylesheets goes into
>  >> /usr/share/sgml/style/foo-3.2.styles, and teh catalog snippet goes
>  >> into /etc/sgml/catalog.d/foo-3.2 
>  >> 
>  >> Next, the post instal script calls update-catalog, and the
>  >> sgml.catalog is regenerated from all the snippets.
>  >> 
>  >> On an upgrade, the contents of /usr/share/foo and
>  >> /usr/share/doc/foo are replaced; but the catalog snippet persist
>  >> across versions.
> 
>  Jorge> How does Debian packages know that they _can't_ remove the DTDs or
>  Jorge> stylesheets or the catalog?
> 
>         The files that are in the .deb, and unpacked into
>  /usr/share/doc/foo, and /usr/share/foo, are automatically removed by
>  the package management syste. However. the files put into place by
>  the post install script shall not be removed unless specific action
>  is taken by the package maintainer. Package maintainers follow
>  policy, and that prohibits removing the DTD's in the post removal
>  script. 

This is exactly the same with RPMs. But, this is too package
specific. Other platforms or package types don't have this facility. 
(At least, I presume installing with as little resources needed as
possible).
 
>  Jorge> In RPM I can do such a thing by copying these files and not
>  Jorge> declaring them in the package (I'm not a RPM guru so there may
>  Jorge> be other ways to do that).  The drawback would be that when I
>  Jorge> ask for which files belong this package, these won't be
>  Jorge> listed.
> 
>         True eough. But while you have the foo package installed, thse
>  files are copies of files in /usr/share/foo; and a simple 
>   % dpkg -S foo.dtd
>  shall give you the answer.

Again both of us are using specific characteristics of our package
system. 

>  Jorge> Another problem is that when I ask which package these
>  Jorge> files belong to, there will be no package who onws them.
> 
>         The only other way to do it is to have the version embedded in
>  the package name, and to never uninstall the package. So, we can have
>  foo-3.2 package, which is different from foo-3,3 package, and you
>  don't remove foo-3.2 while you need the dtd.
> 
>         This is the approach we use for kernel-image packages. 

If you just install packages and never update them, you'll get the
same results and without adding the number of the version in the
package, what make things a little confuse at the user viewpoint: why
do some packages have version numbers as it's names and others
don't? 

>  Jorge> It possible to have such implementation, but them will hasve
>  Jorge> to fix our packaging tools. They'll have to be addwed a
>  Jorge> permanent flag so that some files which belonged to
>  Jorge> e.g. Foo-3.2 now belongs to Foo-3.3 or Foo-4.0 and were not
>  Jorge> changed.
> 
>         The way Debian would handle it would be to 
>   a) Have the DTD's and stylesheets and all belong to no package, and
>      hence be always on the system, or,

What can make things become messy in the future... How would you know
which package you have to install to have the same resources on
another machine? If you don't know who owns that specific file it's
possible that you forget adding it's package...

>   b) To have packages with version numbers in the name itself. In this
>      case, the packages are meant to not be ever upgraded, since
>      foo-3.3 is not an upgrade for foo-3.2, but a different package.

Comments above and also on the kernel issue.

>  Jorge> There'll be also these version specific files, which
>  Jorge> might be the same (and then we'll be wasting disk space) or
>  Jorge> newer ones and differ only in the version number.
> 
>         How does this differ in the other implementation? If the dirs
>  have versions in them, we still have the problem of wasted disk
>  space. 
> 
>         I still feel that the implementation details like this are
>  probably too closely bound to the distribution; and should not be
>  dictated by the standard.

Me too. But a correct directory planning might reduce these
dificulties and make it possible to have a coherent system
everywhere. 

>  >> The end result is: 
>  >> Almost all dtds reside in /usr/share/sgml/dtds,
>  >> Almost all character sets  reside in /usr/share/sgml/charsets
>  >> Almost all entities reside in /usr/share/sgml/entities
>  >> Almost all stylesheets reside in /usr/share/sgml/stylesheet
>  >> 
>  >> (I say almost all since there is provision in our policy for 
>  >> things akin to /usr/share/sgml/dtds/Blah, analogous to /usr/bin/X11) 
>  >> 
>  >> The added advantage of this simplified structure is that
>  >> simple scripts and humans do not have to go rooting through the
>  >> catalog to find out where the DTD is, or where the stylesheet lies.
> 
>  Jorge> In our suggested structure, there's no need for human intervention
>  Jorge> too. The catalog is updated (or not - it's a packager decision) by a
>  Jorge> simple script which add the line
> 
>  Jorge> CATALOG "/path/to/specific/catalog"
> 
>         You are missing my ppoint. I am looking for a certain
>  construct in a stylesheet -- or a certain dtd, which is in a package
>  that has several dtd's, not all of which have the same name as the
>  package. Perhaps I don't even know the name of the DTD or the
>  stylesheet. The script does not help me here.

It does. If you have lots of DTDs in the same package, then you'll
certainly have a catalog. This catalog is all what the system needs to
know how to convert public identifiers on filenames (system
identifyers). 

>  Jorge> (conformant with OpenCatalog specs) to the main catalog file. The
>  Jorge> other files can go anywhere the packager wants but the recommended
>  Jorge> place is /usr/share/sgml/application-dir 
> 
>         There are two minor issues I have with this :
>  a) Not all the tools I use honour the CATALOG setting.
>  b) Scripts that edit files make me feel vaguely uneasy.

a) These tools are broken. OpenCatalog is an already existing
standard. You should talk to the programmers of these tools and ask
them to support it. We shouldn't make a standard work as a workaround
of existing tools. Tools should adapt to it and not it to adapt to the
existing tools. 

b) even if it was written by you or if you have it's source? It just
adds or remove the "CATALOG file" line deppending on if you're
installing or removing a package. 

>  >> Also, I, personally, find it convenient to just browse the
>  >> files in /usr/share/sgml/stylesheets/* while trying to learn by
>  >> example. 
> 
>  Jorge> And how would you know easily what files belong to, lets say, the
>  Jorge> famous "play" example (the one used to markup theater pieces and
>  Jorge> novels)? 
> 
>         Simple: grep through the Contents file which has the
>  package:file association of all packages in Debian, or use dpkg -S,

Too specific for a distribution. It should be easier. How would people
who uses SunOS do that? 

>         I understand these are distributin specific tricks, but I am
>  sure toher distributions ahve similar ones.

SunOS? FreeBSD? Solaris? Slackware? AIX? 

>  >> You see, people who create distributions do not need a spec to
>  >> tell them to keep directories around in order to have a working SGML
>  >> infrastructure -- indeed, I think the current directory structure is
>  >> an overspecification that I'd find very hard to interleave into my
>  >> local policy. 
> 
>  Jorge> As with any standard, you can choose to accept it's
>  Jorge> recommendations or to ignore them. Accepting will make your
>  Jorge> product compatible and easier to work
> 
>         The latter is debateable. If the spec is overengineered, it
>  may *not* be easier to work with. By overspecifying, based on
>  practices designed by the standards writer, may hinder _better_
>  practices discovered later. 

Then the standar should adapt itself to what's technically
better. Stagnation is bad. We live in a dynamic world with technology
and concepts evolving too fast to just stagnate and adopt some
technics that are bad just because once they were good. 

>         At the very least, an effort should be made to discover the
>  state of the art, and try to have the standard accomodate as many of
>  the practices as possible,

That's why we are having this debate :-) 

>  Jorge> (since people will already know how things are organized in
>  Jorge> there and how they do work). Ignoring them will make your
>  Jorge> product less compatible with this standard.
> 
>         And the value of conformance, or even compatibility, depends
>  on how popular this standard is. and popularity also depends on how
>  easy the standard is to work with, and how many changes are
>  required. 

That's exactly what I'm concerned with. As I say below, changing some
files we can do anything but we are trying to do many things with
little or no change to any file. 

>         I do not think a standard like this should dictate the *how*,
>  just the *what* (if I may use the terms). ANd the what should be the
>  minimal required for interoperability. 

I agree. If it can also reduce someone's job (convertion tools
programmers, packagers, system administrator's, etc.) it's even
better! 

>         I fail to see why directories with version embedded are
>  required, given a catalog, and I fail to see why a script is
>  required, since there are perfectly good ways for people to construct
>  the catalog file that ware less susceptible to failure than a script
>  that edits files.

A directory with version is required for not mixing differente
versions of the same catalogs -- which may have files with the same
name.

A directory for each package is required for not getting things messed
up and for reducing patching needs. If we change some key files we can
do anything. We are trying to do things with the minimal changes
possible. 

I'll be happy to continue this talk at
docbook-tools@bazar.conectiva.com.;br mailing list. It's a list with
little traffic and it has it's archive at
http://listas.conectiva.com.br/listas/docbook-tools 

Thanks and sorry for this extra amount of traffic. 
--
Godoy.	<godoy@conectiva.com.br> 

Setor de Publicações
Publishing Department                   Conectiva S.A.