Re: Documents vs. Sections
On Mon, Apr 27, 1998 at 04:04:57AM -0400, Adam P. Harris wrote:
>
> Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de> writes:
> > I think the best way to provide sections with doc-base is to include
> > them in some sort of a registration file:
> >
> > Section: /instadm/hardware/laptop
> > Title: Laptops
> > Abstract: Linux has native support for hardware usually found in laptops,
> > like PCMCIA and APM.
> >
> > I think this are the only three things interesting (am I missing
> > something?).
>
> Yes. It looks like you need to read the doc-base Manual, since it
> describes this better. Here's an example from there:
>
> Document: doc-base
> Title: Debian doc-base Manual
> Author: Christian Schwarz
> Abstract: This manual describes what doc-base is
> and how it can be used to
> manage online manuals on Debian systems.
> Section: Apps/Programming
Uhm, now you are missing something ;) I didn't mean to use the format
described in doc-base, but only *some* format like this in general (as I had
tthe impression that the doc-base registration format is still subject to
changes). However, I think:
"Author" does not make sense for sections, as sections themselfes are not
worth an author mentioned, and the author of DDH is mentioned elsewhere.
"Section" is interpreted differently here, it is the 'document' to
'register' (as I wanted to describe a section registration above).
I just wanted to make sure that you guys keep in mind the difference between
documents and sections in the registration field.
> > I will work on the transition from my free form ascii structure to
> > this format (because I can easily strip additional fields for
> > internal use by me ;)
>
> Marcus, it's not free-form, it's an RFC-defined standard, the best
> example beign email headers or dpkg control files. Note you broke the
> standard format by not having whitespace in your continuation of the
> 'Abstract:' line.
As long as it is on my hard disk, it *is* free-form. Please read again what
I wrote more carefully: I am planning to use an internal format (very
similar to the format of doc-base), where I'll keep additional information
about the sections (for example the explanation for debian developers or
whatever suits me). I'll use scripts to extract the doc-base files then, and
those will surely conform to any standard you define for section
registration.
> Other notes:
>
> * sections do not start with '/', I don't see why they should, and
> they don't now. If you disagree (anyone!) give reasons why.
No, I don't disagree. It was just a sloppy draft, not meant to be
implemented this way.
> > If it is too difficult to make the parser intelligent enough to keep
> > Sections: and Documents: apart, please rename the Section: field of
> > documents. Probably to Placement: or Location:.
>
> What? I don't get this at all.
Let me restate this: Please make sure doc-base gets the difference between a
document registration and a section registration.
> > It would probably be a good idea to forbid Section: fields in package
> > registrations by default. The reasons are explained in my other mails and
> > are not repeated here. It would then be a bug for a package to have a
> > Location: field that does not match with any Section: (this check would be
> > easy).
>
> We need a section "tag" or header to define what section a document
> goes to. How are we going to know what section to put a document in
> if it's not spelled out in a documentation registration file?
The "Section:" above was meant to be a section registration, sorry for the
confusion. In the meanwhile, this has changed, a package may create
subsections.
> > An optional line:
> >
> > Section: /devel/debian
> > Linkto: /debian/devel
> >
> > will be used if Section is only virtual. In this case, it is an error to
> > place a document under the Section: name. Instead, it should use a valid
> > non-link name, as links may be deleted or changed (and then no document
> > registration should be needed to change). Links are only for convenience of
> > the user, like /usr/bin/X11.
> >
> > The point is that a document is not allowed to register under a link name,
> > it has to use the proper Section: name.
>
> Maybe I just don't understand what you're saying here, again.
Yes, this seems to be the case. Let me explain: There will be three sorts of
registrations:
* Document Registrations --- a document needs to define one or more sections
where to be placed. The sections have to exist before they can be used.
* Section Registrations --- the DDH shipped with doc-base and packages
create sections, where documents can be stored. A section needs a shortname,
a title and an abstract. Probably further tags that are useful in this
context (language, ...)
* Link Registrations --- the DDH will contain *very* few *section crosslinks*
between different sections of the hierarchy. Thsoe are only meant as a
convenience for the user and to support the logical structure. Only the
DDH may create such links. From DDH -guidelines:
§2. What the DDH will provide
[...]
No documents should be installed in or below a link,
because links are provided for user only. Instead, the appropriate section
(probably the section the link is pointing to or a subsection of it) should
be used.
c) The links will not be circular. This means, whatever way the user is
choosing down the hierarchy, he will never come to the same point twice.
As the number of section is finite, this grants that the search will
come to an end. The reason for this requirement is that it is very
confusing for the user if he finds themselves turning 'round and 'round.
Note that this does not mean that a link is not allowed to point to a
higher level in the hierarchy (as long as the branches are seperated).
I hope this clarifies things a bit.
> I guess you're trying to deal with cross-linking. From my
> understanding of your guidelines, you've setup something analogous to
> directory symlinking in the unix file systems as the sole facility for
> cross-linking. However, I don't think this facility is adequate.
>
> Let me paint an example. Say I'm the debiandoc-sgml maintainer, and
> say we have these area in the heirarchy (which we don't but maybe
> should):
>
> debian/devel/maint/doc -- documentation policy for debian pkg maintainers
> reference/sgml/dtd -- documentation for SGML DTDs
>
> Now it's natural as the debiandoc-sgml maintainer that I would want to
> document this DTD in both sections. Do we necessarily need to create
> a "virtual section" to accomplish this? From my readings of your
> guidelines, we do.
Nonono. Links are only provided where the structure of documents can't be
realized in a tree structure, but needs some way to "escape". This will be a
rarely used method for crosslinking, as it links whole sections together!
Documents should use whatever procedure we define to register themself in
two sections. They should actually register twice:
Document: foobar
Author: Mr. Brown
Abstract: The brown fox doesn't jump anymore.
Section: devel/lang/perl
Section: usr/games
> To the contrary, I would suggest that we allow a single document to
> appear in as many documentation sections as the maintainer sees fit
> (i.e., more like a symlinking of files, as well as the possibility of
> the symlinking of directories).
Yes, this is what I meant for files. The directory linking should not be
used by packages, as this may be confusing and lead to circular links and
all sort of nasty stuff. Directory links may only be used by the DDH where
there is a need for them (note that some of the links in the first draft
were removed as Marco suggested. I approximate the actual number needed in
the end below 10.
> Moreover, in both the "virtual section" and the "multiple section
> appearance" cases, the debian pkg maintainer should not have to know
> or care which place is "cannonical" and which place is symbolic,
> keeping the fs metaphor. As such, I would propose that the Section
> header could have the following new semantics:
>
> Section: <section> [<additional_section> ...]
Okay, similar to what I have above. We really want the same here. The links
are only for special cases. Sometimes you need a way to go back in a tree
hierarchy. Packages mustn't create those dir links.
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: