Re: Documents vs. Sections
Marcus, it looks like I was confused on what you were doing here.
Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de> writes:
> On Mon, Apr 27, 1998 at 04:04:57AM -0400, Adam P. Harris wrote:
> > Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de> writes:
> 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).
Right, we're talking about the DDH file which hold the heirarchy of
sections. This is clearly centrally adminstered, etc, and probably
delivered from doc-base. I hadn't really thought about this file. ;)
But it makes sense we need it, and in a std format so other packages
can access the current heirarchy.
> > 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.
Oh.... heh. Of course you can do things internally however you like.
> > > 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.
Yes, I agree; making the debian documentation registry (DDR) file and the
DDH files too similar will confuse people.
> 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.
Or "application subsections" as I like to call them. ;)
> 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.
Right. This is the the DDR which I am defining.
> * 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, ...)
Hmm. I think language is more relevant to the labelling rather than
the structure itself (in contradistinction with dhelp). I.e.,
translations of the DDH for German systems...
The language issue is very sticky... lets see you get your 2nd draft
out and me get my first draft out then we'll make sure we have good
coverage of language issues.
[...]
> I hope this clarifies things a bit.
Yes very much.
> 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
Well, assuming sectional names never have spaces in them, I would make this
Section: devel/lang/perl usr/games
Or what have you. Otherwise we're starting to break the file format
(RFC 822). And god knows I don't want to introduce repeating groups
(i.e., 'Section0', 'Section1').
> > 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.
Gotcha.
> > 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.
Right. But documents *can* create as many document-leve links as they
like. Agreed.
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: