Draft new policy document format
Hi,
At Debconf earlier this year, I gave a talk about the benefits
of creating language for a lintian/linda check whenever we introduce a
new policy rule (when appropriate, and feasible, of course). Not only
do we get a instant Lintian check, but it would also tend to focus the
discussion and design of the policy rule.
There a re a number of bits and pieces of policy scattered
across several documents, not all of which can be found in the policy
package. These documents cover different areas, Menu, Python, Perl, X,
etc. They also are at different places in the spectrum from release
critical measures to best practice recommendations.
Also, there are various levels at which people tend to approach
the policy document; some people prefer reading the document by
topics; which is useful is one is packaging something in a topic area
covered by multiple policy documents; others just want to see the
"hard" policy rules, and defer best practices until later, to prevent
being drowned in a flood of information.
Then there is the dimension of Debian sub projects and
Derivatives, who would perhaps benefit from deriving from Debian
policy, but adding some specialized directives of their own.
One solution that enables all these use cases is doing a set of
books, each book being a separate entity, with different author sets,
but all using a common schema; each rule is an entity, has title,
severity, normative section, rationale, informative section, and
lintian psuedo-code. Each book can have separate copyrights, SCM
systems, and can even be compiled and published separately.
Each rule can become a separate XML entity, and live in a shared
location on disk like /usr/share/debian-policy/<some dir structure>.
This way, you have a published book, and a dev version that has the
entity definitions in a well known place; and people can create their
own sets, reorder the rules, select only rules in a certain topic area,
add rules of their own, or whatever.
In other words, you can then cherry pick the best part of each
others manuals/
I had a conversation earlier with Roland Mas, he says that
it's pretty easy then to write an XSLT stylesheet, or a Perl script,
that could parse the set/book/article/rule and ensure that all required
sections are present in the correct order. You can even decide to show
or hide various sections when rendering a final document; for instance
if you want to generate a PDF of only the normative part of the Perl
policy, you can decide to hide the lintian code and rationale; again,
it's "a simple matter of XSLT".
With this in mind, I have created an initial draft format of the
Debian technical policy set, and am including it in this mail.
Comments appreciated.
manoj
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";>
<set>
<title>The Debian policy Manual Set</title>
<titleabbrev>Debian Policy Set</titleabbrev>
<setinfo>
<author>
<firstname>Manoj</firstname>
<surname>Srivastava</surname>
</author>
<copyright>
<year>2007</year>
</copyright>
<legalnotice>
<para>
This set outline free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
</para>
<para>
This document is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this document; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
</para>
</legalnotice>
<corpname>The Debian Project</corpname>
<revhistory>
<revision>
<date>November 30<superscript>th</superscript>, 2007</date>
<revdescription>
<remark>Initial draft</remark>
</revdescription>
</revision>
</revhistory>
</setinfo>
<book>
<title>The Debian Technical Policy Manual</title>
<bookinfo>
<author>
<firstname>Manoj</firstname><surname>Srivastava</surname>
</author>
<copyright>
<year>2007</year>
</copyright>
<legalnotice>
<para>
This set outline free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
</para>
<para>
This document is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this document; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA. A copy of the GNU General Public
License is available as
<filename>/usr/share/common-licenses/GPL</filename> in the
Debian GNU/Linux distribution or on the World Wide Web at
the GNU General Public Licence
<uri>http://www.gnu.org/copyleft/gpl.html</uri>.
</para>
</legalnotice>
</bookinfo>
<preface>
<title>Foreword</title>
<para>
I became involved in the Debian technical policy document
nearly a decade ago (at the time of writing), in 1998. Almost
from the beginning I wanted to move the technical policy
document away from the original format, and into something
more well established, like DocBook. With this draft, that
goal has come withing sight.
</para>
<para>
This manual describes the policy requirements for the Debian
GNU/Linux distribution. This includes the structure and
contents of the Debian archive and several design issues of
the operating system, as well as technical requirements that
each package must satisfy to be included in the distribution.
</para>
</preface>
<chapter>
<title>Chapter Title</title>
<abstract>
<para>
What the chapter is all about
</para>
</abstract>
<section>
<title>Section Title</title>
<abstract>
<para>
What this section is all about
</para>
</abstract>
<section role="PolicyRule">
<title>Policy Rule Example</title>
<para role="priority">
<property>MUST</property>
</para>
<para role="topic">
<property>Control files and their fields</property>
</para>
<authorblurb>
<para>
This rule was contributed by Alice and Bob.
</para>
</authorblurb>
<section role="Check">
<title>>Lintian Rule</title>
<programlisting>
Psuedo code for Lintian check
</programlisting>
</section>
<section role="Normative">
<title>Normative Content</title>
<para>
Actual policy rule
</para>
</section>
<section role="Informative">
<title>Informative Content</title>
<para>
Nor normative content, explanations, etc
</para>
<example>
<title>Usage Example</title>
<para>
Synopsys and examples
</para>
</example>
<section role="Rationale">
<title>Rationale</title>
<para>
A rationale for the policy rule
</para>
</section>
</section>
</section>
</section>
</chapter>
</book>
<book>
<title>The Developers reference</title>
</book>
</set>
--
"Ignorance transcends architecture." James Gaskin
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: