Re: Tutorial in one huge file
olet@ifi.uio.no (Ole J. Tetlie) writes:
> Is it possible to split the tutorial in one file per chapter
> (or is that stupid). That would make things easier when producing
> diffs and would make checking in less likely to disrupt others.
It certainly *is* possible, if Havoc wants to do this. I'll include
the SGML source of my Metadata Policy which does this.
--
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
<!doctype debiandoc system [
<!entity revision "$Revision: 1.4 $">
<!entity date "$Date: 1998/07/01 05:50:48 $">
<!entity copyrightstmt SYSTEM "copyright.ent">
<!entity ch-sysadmin-config SYSTEM "sysadmin-knobs.sgml">
<!entity ch-metadata SYSTEM "metadata-elements.sgml">
<!entity ch-docreg-fmt SYSTEM "docreg-format.sgml">
<!entity ch-api SYSTEM "metadata-api.sgml">
]>
<debiandoc>
<book>
<titlepag>
<title>Debian Metadata Project</title>
<author>
Adam P. Harris <email/aph@debian.org/
<author>
The Debian-Doc List <email/debian-doc@lists.debian.org/
<version>&revision;</version>
<abstract>
This manual contains a guide and a reference to the Debian Metadata
Project. The Project's purpose, and the purpose of this document, is
to outline a set of metadata elements, to specify an interface for
package maintainers use in order to provide metadata about resources
in their packages, to specify a unified subject catalog for
categorizing metadata, and to specify an API for developers who wish
to make use of a system's metadata.
This manual is intended to serve as sub-policy for the deployment and
utilization of metadata in Debian. Currently, it carries no actual
force and is for informational purposes only. The manual is intended
for both package maintainers, Debian document writers, and those
implementing document display systems such as <prgn/dwww/ and
<prgn/dhelp/.
<copyright>
©rightstmt;
<toc sect>
<chapt id="ch-intro">Introduction
<p>
What is metadata? Metadata is information about information. The
Debian Metadata Project is an attempt to provide a robust,
standards-based metadata set, and the facilities to collect and
display information about resources (usually, documents on a user's
machine). Collected information includes the document's title,
author, format, placement in a subject catalog, description, the
language it is in, etc.
<p>
Why should anyone care about metadata? Well, primarily, it is useful
in <em/resource discovery/. This is the process of finding out where
to find information. You do this every time you run <prgn/man -k/ or
<prgn/apropos/; Altavista and HotBot are typical of the current
technologies in resource discovery. But <em/metadata/ allows you to
find resources in different and better ways. You can search by title,
by language, by author; you can traverse a subject heirarchy, like a
book's index. Metadata allows a more intelligent was to organize and
present the vast amount of documentation that Debian already provides.
<p>
Debian uses as their metadata entity definition a specialized
application of the Dublin Core
(http://purl.oclc.org/metadata/dublin_core/). The Dublin Core is an
informal standard formulated by an international group of professions
in the fields of library science, and the networking and digital
library research communities.
<sect>Organization of this Document
<p>
The document is split into three main sections. The first section
contains information of interest to any Debian user, curious about the
features and capabilities of our metadata system. The second section
is of interest to package maintainers. The final section is mainly of
interest to documentation system providers or metadata display system
developers.
<p>
System administration controls provided by the Debian Metadata system
is documented in <ref id="ch-sysadmin-config">. <ref id="ch-metadata">
defines the metadata elements, which are the data fields which can be
populated for a given resource.
<p>
The part of this manual is primarily of interest to Debian package
maintainers. It begins with <ref id="ch-docreg-fmt">, which describes
the "docreg" file, the file that the package maintainer uses to
<em/register/ document metadata into the local document store.
Finally, in <em/section not yet written/, the use of
<prgn/install-docs/ is covered. Developer tools to convert metadata
to and from HTML is discussed in <em/section not yet written/.
<p>
In the final part, of interest to those who are working with Debian's
metadata collection, we start in <ref id="ch-api"> with a discussion
of the API used to access the document store. In <em/section not yet
written/, we discuss how developers can hook into <prgn/install-docs/
in case they need to capture certain metadata events or shadow data (a
deprecated practice).
<sect id="sec-contributing">Contributing to the Project
<p>
Discussions about the Debian Metadata Project generally take place on
the <debian-doc@lists.debian.org> mailing list. This is an open
project; all are invited. To subscribe to this list, go to
http://www.debian.org/MailingLists/subscribe .
&ch-sysadmin-config;
&ch-metadata;
&ch-docreg-fmt;
&ch-api;
</book>
</debiandoc>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: