Marcus Brinkmann <[EMAIL PROTECTED]> 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 > 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. 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. > 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. > 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? > 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. 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. 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). 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> ...] .....A. P. [EMAIL PROTECTED]<URL:http://www.onShore.com/> -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
