Re: Documents vs. Sections
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
> 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. 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: