Re: Draft new policy document format
On Sun, 2 Dec 2007 12:34:28 +0100, Stefano Zacchiroli <zack@debian.org> said:
> On Sat, Dec 01, 2007 at 12:29:28AM -0600, Manoj Srivastava wrote:
>> At Debconf earlier this year, I gave a talk about the benefits
>> Comments appreciated.
> As a general comment, before seeing an actual XML-like format I would
> like to see a list of what semantic information a document in such a
> format should be able to express. E.g. "a set of rules, each of which
> with a mandatoriness level which is one among MUST/SHOULD/... bla bla
> together with bla bla". Can you please summarize such information for
> us?
Ultimately, the document in such a format should be able to
express what the current policy documents do. Do we really need to
define what the technical policy expresses?
> In addition to that, just some tiny nitpicking below.
>> <section role="PolicyRule"> <title>Policy Rule Example</title>
>>
>> <para role="priority"> <property>MUST</property> </para>
> I find this use of <para> inappropriate. The role is fine, but the one
> thing above is definitely not a paragraph, so it should not be tagged
> as such.
Well. It is a paragraph, with a single word as a content. I'm
pretty sure that is legit, in English, as well as in XML. If you wish,
we can make the paragraph longer, by sticking in a definition of the
priority, which helps when looking at the rule in isolation, but would
tend to get boringly repetitive when reading a manual.
However, I am willing to change this to a better alternative.
> Unfortunately I'm writing this email offline so I'm unable to check
> whether docbook has any more appropriate element for this or where
> else can be but a <property> element, but something better then this
> should be looked for.
These elements contain property: action, application, attribution,
bibliomisc, bridgehead, citation, citetitle, classsynopsisinfo, code,
command, computeroutput, database, emphasis, entry, filename, firstterm,
foreignphrase, funcparams, funcsynopsisinfo, function, glosssee,
glossseealso, glossterm, hardware, interfacename, keycap,
lineannotation, link, literal, literallayout, lotentry, member, msgaud,
olink, option, optional, para, parameter, phrase, primary, primaryie,
productname, programlisting, property, quote, refdescriptor,
refentrytitle, refname, refpurpose, remark, screen, screeninfo,
secondary, secondaryie, see, seealso, seealsoie, seeie, seg, segtitle,
simpara, subtitle, synopsis, systemitem, td, term, termdef, tertiary,
tertiaryie, th, title, titleabbrev, tocback, tocentry, tocfront,
trademark, ulink, userinput.
manoj
--
It's later than you think.
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: