Re: DEP5: minor suggestions - FSF address etc.

[Charles Plessy <plessy@debian.org>]

Le Mon, Feb 13, 2012 at 11:25:38AM +0800, Thomas Goirand a écrit :
> 
> So, something like this:
> 
> Copyright: 2012, John Doe <john@debian.org>
>   2012, Homer Simpson <homers@debian.org>
> 
> rather than:
> 
> Copyright: 2012, John Doe <john@debian.org>
>  2012, Homer Simpson <homers@debian.org>
> 
> right? If so, could this be written explicitly in the DEP5
> specifications (probably with the above example or
> something similar)?

Bonjour Thomas,

currently, the DEP describes the copyright field as a “formatted text” field
with no synopsis.  The description of the field is the following:

  Formatted text fields use the same rules as the long description in a package's
  Description field, possibly also using the first line as a synopsis, just as
  Description uses it for the short description. See Debian Policy's section
  5.6.13, "Description", for details. For example, Disclaimer has no special
  first line, whereas License does.

  (http://dep.debian.net/deps/dep5/#formatted-text)

It is a bit misleading that the title above this paragraph is “Text formatted
like package long descriptions”; I think that it makes it more difficult to find
the definition of “formatted text” fields.

How about the following.

1) Adding hyperlinks to the field's type description in the definition of each
   field.  For example:

  <h3 class="section"><a name="copyright-field" id=
  "copyright-field"><code class=
  "varname">Copyright</code></a></h3>

  <p><a href="#formatted-text">Formatted text</a>, no
  synopsis: one or more free-form copyright statement(s)
  …

2) Replacing the title “Text formatted like package long descriptions” by
  “Formatted text”.

We could add a warning that Debian control file's “Description” field's syntax
includes verbatim sections, but on the other hand that is something that every
developer should know, or will learn by clicking o the hyperling to Policy's §5.6.13.

For the examples, I do no think that it is a good idea to include examples of
things to not do.  First, the possibilities are endless, and second, they may
be confused with examples of things to do.

Then, for the indentation of the current examples, that is the same as what
a helper tool (config-model) is doing, but other choices are equally valid.
In that sense, the examples are arbitrary and I do not think that replacing
one style with the other will change how people understand the specification.

If you or others think that the quality of examples is a blocker for the relase
of the version 1.0 of the spec, please raise your hand and make concrete and
comprehensive propositions.  I intend to mark this DEP accepted this week
(Japan time; some timezones are still on week-end) unless critical problems
are reported or delays are asked with a timeline.

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan