Re: Re^4: Debian Metadata Proposal -- draft rev.1.4
On Tue, Jul 07, 1998 at 07:50:00PM +0100, Marco Budde wrote:
> Am 06.07.98 schrieb Marcus.Brinkmann # ruhr-uni-bochum.de ...
>
> MB> Marco, I really hate the howto section in the DDH. I don't hate the idea
>
> I can#t understand this. As maintainer of several howto packages I think
> we should have such a section.
Marco, listen. If I go in a book store, I can ask two types of questions:
a) "I would like to buy one of those Marco Polo Travel Guides "
b) "I would like to buy a Travel Guide for Europe".
The "Subject:" line implements ordering as required in question "b)", the
"Type:" field does ordering as requested in qquestions of type "a)".
In book stores, you'll notice that most books are sorted like the DDH, with
questions of type "b)" in mind. Sometimes, you'll find additional displays
of all Marco Polo books for example. This is helpful if you only read marco
Polo travelguides.
Can you see the analogy? Most people want to know how he can install a
firewall, and cares nuts if it is a FAQ or a HOWTO. If you already know you
need the Howto, you can go to the Howto display.
Now to the DDH. The DDH implements ordering as in "b)" above. There is no
natural place for displays of "howto"'s or "faq"'s. This is only natural.
If you really can't see the distinction between "Subject:" and "Type:", I
beg you to believe Adam, me, and other people, who can. I really tried to
explain it multiple times now.
> MB> to access howtos in a single section, but I hate the orthogonality of DDH
> MB> and Document Type. I think the Type: field is the correct solution for
> MB> this problem. I hoped you would recognize this and would be happy that
> MB> this is adressed properly. In some way, it was requested by you.
>
> I think the Type tag is very inconsistent. And where#s the difference for
> the user?
Mayybe in dhelp is no difference for the user (in dhelp, the type "howto"
could just be another section). If I would implement a frontend for
doc-base, I would make sure that the user benefits of the additional
information. I don't understand why you think the Type tag would be
inconsistent. Is this just a personal feeling or a technical contribution?
> MB> I don't think Type is trivial, btw. I think it is a *mayor* improvement,
> MB> because it allows flexible data access, much more flexible than
> MB> implementing howto and faq sections in the DDH.
>
> And how would you describe all other documents with type? Using type will
> produce a lot of work for the package maintainers without any improvements
> for the users.
"Type:" is an optional tag. Documents that clearly have an associuated type
(as howto's and faq's) will carry it. Other may not.
> MB> I too can't understand why Marco objects against an optional field. Marco,
> MB> you don't need to implement it in dhelp. What exactly is your technical
> MB> argument?
>
> That#s right, I#ll not use it. An argument is space on the local disc. Why
> should we add the same information several times to the hard disc? I think
> we should make docreg as simple as possible. This will help the
> maintainers understanding our standard.
I don't think it's add complexity, it's just another, optional, field. I
think mainatiners would be more confused by howto and faq section in the
DDH.
The space argument is not applicable. Every file less than block size
(default 4Kb) will use the same amount of disc space.
> And if we think some times later, that we need such a tag, it#s no problem
> to add it.
Better do it right from the very beginning.
(I had a point-for-point reply here but removed it in favour of my summary
at the end of the mail, where things are better adressed).
> 1.) With your solution you can only support one subdir (/usr/doc).
> But we should offer support for every location (for example
> /usr/local/doc).
? We do support every location that complies to URL standard. We just don't
support it as relative link. One can always use absolute paths.
> 2.) With your solution we will have a problem to move from
> /usr/doc and /usr/share/doc, see (1).
Not really. There is a good work-around for the transition perio (scanning
both directories).
> 3.) Commercial programs my include docreg files under /opt, see (1).
So what? See (1).
> 4.) Relative links are always better, html itself uses in most cases
> relative links! Or read the link chapter in the policy.
Attention, now follows a strong point, IMHO:
====================================
This isn't about html at all!
------------------------------------
We try to define a metadata
standard. The metadata standard
consists of a plain ascii file.
The location of an ascii file in
the local file system should not
make any difference!!! I think a
data file concept where the stored
data changes meaning when the data
files are moved is heavily flawed.
Marco, how would you implement
the relative path in database re-
pository?
=====================================
The docreg files are parsed, and not "executed" like html pages. So they
should be as unambigouus as possible.
Proposal: Let's drop the relative link concept at all. Every docreg file
should specify the whole valid URL, then we avoid all problems (including
the problems with the file system transition).
In the database, the real path has to be stored anyway. Adam?
> 5.) If a package maintainer has to move a doc directory to another
> directory he don#t need to change the docreg file! He moves only
> the docreg file to the new location:
>
> /usr/doc/<foo>/ -> /usr/doc/<foo>/html
>
> He has only to change one line in rules:
>
> cp docreg usr/doc/<foo>
>
> to
>
> cp docreg usr/doc/<foo>/html
I think this is a misconcecption for a metadata concept. It may be useful
for the actual represantation of files (for example for web pages), but not
for abstract data files. I don't want the content of the docreg file
dependent on the location in the file system. See above.
> 6.) Upstream maintainers could deliver docreg files. It#s not a problem
> to which location the distributors will move the documents.
This supports me in my opinion that the links should be absolut from the
beginning.
> 7.) You can include docreg files to tar archives (they use relative
> paths). Example: binary distributions, commercial software.
I think you are advertising false security here. It actually *works* as you
describe it, but only once. If I move the extracted tar file after
registration of the docreg file and putting it in the repository, it won't
work anymore.
Marco, I see where you are coming from, but it won't work because the docreg
file is parsed one time only. The database has to store *some* absolute
path in any way. The relative path concept is only a convenience for Debian
maintainers. Debian packages are under the control of the respective
maintainers, and sysadmins are not supposed to move things around, and the
install scripts will care about the up-to-date'ness of the database.
For local files, the doc-base install docs file must be called anyway when
something is moved, regardless whether the location is absolute or relative.
Okay, I'll try to summarize the mess:
(Note: I'm not trying to put words in anybodies mouth. Marco, if I
misrepresented your position, please correct me).
Fact1: We are only talking about relative "Identifiers:" here.
Fact2: The docreg file is only parsed once. Whenever something changes, the
install-docs procedure has to be called in some way.
Question: Do we want to support relative "Identifiers:" and if yes, where
should they point to?
Do we want to support relative "Identifiers:"?
==============================================
YES, because
+ they are convenient for the maintainer.
NO, because
+ there is probably no consistent solution to handle them.
How should a relative "Identifier" be handled?
==============================================
Marco: It should be a location relative to the location of the docreg file.
Consequence:
The location of the file in the file system becomes important in the
interpretation of the data the metadata file contains.
Features:
+ One can move a bundle of documents & associated docreg file without
changing the docreg files content. This implies the transition
from FSSTND to FHS.
- The last point works only before the doceg file is registered
because: (see next point)
- the docreg file is limited to the documents associated to it (and to
external documents). This means, for a central repository, the paths
have to be determined and saved absolut or converted otherwise.
Adam: It should be relative to "/usr/doc" (or "/usr/share/doc" and "/usr/doc")
Consequence:
The data can be stored everywhere without impact on the data
interpretation, for example in a single directory.
Features:
+ The behaviour of relative paths is well defined in all places, even
when the metadata information is stored in a database instead of a
file.
+ The transition from FSSTND to FHS can be work-around without loss.
- Moving the documentation requires editing the docreg file.
Marcus: Drop the relative "Identifier:" at all.
Consequence:
See Adam's proposal.
Features:
+ No undefined behaviour, no surprises.
+ No problems with the FSSTND to FHS transition.
- Moving the documentation requires editing the docreg file.
- A few keystrokes more for the maintainer.
My personal opinion:
I don't think that my proposal is significantly stronger than Adam's in
design. The workaround for the FSSTND->FHS transition is easy and clean
enough to serve everyones needs. So I suggest to drop my extreme proposal
and use Adams.
Marcos proposal looses a lot of its charme because the docreg file is not
used directly by frontends. Every parser has to substitute the relative
link with an absolute link anyway to store it in a repository or elsewhere.
For this reason, the files can't be moved around freely after registration.
Maybe this is missing in the represantation above:
Adam, how are the documents identified? Is the "identifier:" field the
unique identifier used by doc-base to install and remove an entry? Then we
*have* to drop Marcos proposal, because the Identifier is not unique. This
is not a problem in your proposal, because every relative link has first the
package's name.
About the location of the docreg files:
In Marcos proposal, spreading the docreg files has a small benefit. In
Adams proposal, it does not add anything, so it makes perfectly sense to
store them centrally.
Okay, Marco and Adam, I'm prepared for your comments.
Marcus
--
"Rhubarb is no Egyptian god." Debian GNU/Linux finger brinkmd@
Marcus Brinkmann http://www.debian.org master.debian.org
Marcus.Brinkmann@ruhr-uni-bochum.de for public PGP Key
http://homepage.ruhr-uni-bochum.de/Marcus.Brinkmann/ PGP Key ID 36E7CD09
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: