Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Charles Plessy]

Hi Russ and Gregor,

thanks for your feedback,

I think that I made most of the points I was thinking about and hope
that some of them related to Simple English and jargon can be useful in
the future.  I also understand your point of view.  One final comment I
would like to make is that the format is used in other contexts, such as
Apt (using "paragraph" in https://wiki.debian.org/DebianRepository/Format),
DEP-11 (using "block" in https://wiki.debian.org/DEP-11), and probably
other files generated for the Debian archive.  I recommend to keep
producers and consumers of these files in the loop before changing
Chapter 5.  As for on which word to standardise on, I trust the Policy
Editors to make a good choice, even if it is not my favourite.

Have a nice week-end,

-- 
Charles

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[gregor herrmann]

On Fri, 23 Sep 2022 01:03:28 +0200, Guillem Jover wrote:

> In the end nothing will match exactly, and we need to choose some
> terminology. In this case, as previously mentioned, «stanza» has the
> good properties of not usually applying to prose, being short, distinct
> from the other terms and the less ambiguous of them all. It also makes
> constructing sentences to describe things less cumbersome.

FWIW, and knowing this is not a popularity vote, as yet another
non-native speaker-with a different first language-I also like
"stanza" and agree with Guillem's arguments.

Additionally I'd like to mention that also some software uses this
term:

/usr/share/perl5/Debian/Control/Stanza
/usr/share/perl5/Debian/Control/Stanza.pm
/usr/share/perl5/Debian/Control/Stanza/Binary.pm
/usr/share/perl5/Debian/Control/Stanza/CommaSeparated.pm
/usr/share/perl5/Debian/Control/Stanza/Source.pm
/usr/share/perl5/Debian/Copyright/Stanza
/usr/share/perl5/Debian/Copyright/Stanza.pm
/usr/share/perl5/Debian/Copyright/Stanza/Files.pm
/usr/share/perl5/Debian/Copyright/Stanza/Header.pm
/usr/share/perl5/Debian/Copyright/Stanza/License.pm
/usr/share/perl5/Debian/Copyright/Stanza/OrSeparated.pm

(That's dh-make-perl and libdebian-copyright-perl. Also
libparse-debcontrol-perl talks about "stanzas" in its documentation.)
 

Cheers
gregor

-- 
 .''`.  https://info.comodo.priv.at -- Debian Developer https://www.debian.org
 : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D  85FA BB3A 6801 8649 AA06
 `. `'  Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe
   `-   


signature.asc
Description: Digital Signature

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Russ Allbery]

Charles Plessy  writes:

> In the spec, the word "paragraph" is only used in the specified context,
> so I always felt that there is no ambiguity.  But of course, it can
> create opportunities for misunderstanding when discussing about the
> spec.  So point taken about "paragraph", although interestingly, the
> Simple English definition of "paragraph" is quite spot on if one would
> replace "sentence" with "field": ”one or more sentences that are written
> together with no line breaks separating them.  Usually they are
> connected by a single idea.”
> ()

> The use of "paragraph" in the current spec is also consistent with
> Chapter 5 of the Policy, which also uses the word "paragraph".

Right, that's the motivation of this change.  It didn't start as being
about the copyright file, but about Policy.  Guillem was standardizing
terminology in dpkg.

I don't have a strong opinion about what word we choose.  I care more
about a few surrounding principles, specifically:

* We should use the same terminology when describing the copyright file as
  when describing Debian control files (and every other deb822 file).

* Policy should use the same terminology as dpkg.

* I'd prefer we not use the word "paragraph" because we also use that word
  to talk about normal prose paragraphs in the Description control field,
  and may similarly need to talk about prose paragraphs in the copyright
  file.

> By the way, in section 5.6.26 of the Policy, the word "stanza" is also
> used to mean something else than a "paragraph".

Thanks, I think regardless of how we resolve this bug that usage was
confusing.  It was also using two terms for the same concept in the same
section, since earlier the same construction was referred to as a
"portion."  I've fixed this to use "portion" consistently in this section.

-- 
Russ Allbery (r...@debian.org)  

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Guillem Jover]

Hi!

On Thu, 2022-09-22 at 14:26:38 +0900, Charles Plessy wrote:
> Le Tue, Sep 20, 2022 at 06:08:16PM -0700, Russ Allbery a écrit :
> > I do find the use of paragraph the way we were previously using it to
> > be confusing, particularly given that the paragraphs contain fields
> > which in turn contain actual paragraphs in the normal sense of the
> > term.

Idem.

> > I don't want to keep using paragraph, but I'd be open to some other term
> > that Guillem was also open to (I think matching the terminology in dpkg is
> > very important).  Section or block are commonly used for things like this,
> > but aren't very precise, so I'm not that enthused by them.
> 
> In the spec, the word "paragraph" is only used in the specified context,
> so I always felt that there is no ambiguity.  But of course, it can
> create opportunities for misunderstanding when discussing about the
> spec.  So point taken about "paragraph", although interestingly, the
> Simple English definition of "paragraph" is quite spot on if one would
> replace "sentence" with "field": ”one or more sentences that are written
> together with no line breaks separating them.  Usually they are
> connected by a single idea.” ()

In the end nothing will match exactly, and we need to choose some
terminology. In this case, as previously mentioned, «stanza» has the
good properties of not usually applying to prose, being short, distinct
from the other terms and the less ambiguous of them all. It also makes
constructing sentences to describe things less cumbersome.

> I do not mind the word "section".  It is the term used in the manual
> page "systemd.syntax" that describes systemd's unit files, which means
> that readers may be already familiar with the concept.  One could argue
> that its definition in Simple English
> (, “A section of a thing or
> place is a part of it”) would allow a reader to think that a Field is
> also a section, but I feel it is unlikely to happen.  This said, one big
> disadvantage of "section" is that when searching for this word in a
> document, there may be a lot of noisy hits such as "refer to section xyz
> for details".

The problems with section, is that as you mention is not very
searchable, but worse we already have a field with the same name!

> I understand about avoiding ambiguity, but in my opinion it is the price
> to pay to be able to translate information into simple words from
> English to non-European languages.  Although the Policy itself is not
> going to be translated, I think that it can be advantageous if its
> contents can be discussed in simple words in people's native languages.

As a non-native speaker, and a translator, I agree having clear
wording in the original text is important, as otherwise that tends to
make translation work harder. But then, part of that work is to find
or create terminology, in many cases not existing yet in the
translated language, that might be suitable there, trying several terms
that might not necessarily be direct translations.

For a translation anecdote related to finding the right terms, when
triggers got introduced, and having to translate them to Catalan, we
initially used «gallets» (which would be the direct translation). But
when reading them that was bothering several of us as it sounded weird,
it could be read as “small roosters” («gall» being rooster, and «ets»
forming the plural diminutive), or being too close to «galets» which is
a type of pasta used for example in «sopa de galets» ("galets" soup). We
then switched to «activadors» which sounds way nicer, even though it's
not a direct translation. But if we had to translate the spec today,
that would be annoying as it uses «activating» all over the place, so
perhaps using «disparador» would be better. So, in the end this is a
process too, and terms can be changed if they are deemed confusing or
not helping convey the meaning. And in some others, you just need to
simply create new terminology, and describe what it means in specific
contexts.


For example for Catalan/Spanish «stanza» is simply «estrofa» which
seems like a nice term to use here.

Thanks,
Guillem

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Sean Whitton]

Hello Charles,

On Thu 22 Sep 2022 at 02:26PM +09, Charles Plessy wrote:

> So point taken about "paragraph", although interestingly, the
> Simple English definition of "paragraph" is quite spot on if one would
> replace "sentence" with "field": ”one or more sentences that are written
> together with no line breaks separating them.

I think that the quoted definition rather argues against 'paragraph' --
it makes it clear that being made up of sentences, and not
non-sentences, is essential to paragraph-hood.  In other words, it only
becomes spot on if you change the core meaning into a definition of
something else.

> I understand about avoiding ambiguity, but in my opinion it is the price
> to pay to be able to translate information into simple words from
> English to non-European languages.  Although the Policy itself is not
> going to be translated, I think that it can be advantageous if its
> contents can be discussed in simple words in people's native languages.

It may yet be translated!  We have the po4a setup :)

-- 
Sean Whitton

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Charles Plessy]

Hi Russ,

Le Tue, Sep 20, 2022 at 06:08:16PM -0700, Russ Allbery a écrit :
> 
> I do find the use of paragraph the way we were previously using it to
> be confusing, particularly given that the paragraphs contain fields
> which in turn contain actual paragraphs in the normal sense of the
> term.

> I don't want to keep using paragraph, but I'd be open to some other term
> that Guillem was also open to (I think matching the terminology in dpkg is
> very important).  Section or block are commonly used for things like this,
> but aren't very precise, so I'm not that enthused by them.

In the spec, the word "paragraph" is only used in the specified context,
so I always felt that there is no ambiguity.  But of course, it can
create opportunities for misunderstanding when discussing about the
spec.  So point taken about "paragraph", although interestingly, the
Simple English definition of "paragraph" is quite spot on if one would
replace "sentence" with "field": ”one or more sentences that are written
together with no line breaks separating them.  Usually they are
connected by a single idea.” ()

The use of "paragraph" in the current spec is also consistent with
Chapter 5 of the Policy, which also uses the word "paragraph".  By the
way, in section 5.6.26 of the Policy, the word "stanza" is also used to
mean something else than a "paragraph".

I do not mind the word "section".  It is the term used in the manual
page "systemd.syntax" that describes systemd's unit files, which means
that readers may be already familiar with the concept.  One could argue
that its definition in Simple English
(, “A section of a thing or
place is a part of it”) would allow a reader to think that a Field is
also a section, but I feel it is unlikely to happen.  This said, one big
disadvantage of "section" is that when searching for this word in a
document, there may be a lot of noisy hits such as "refer to section xyz
for details".

I understand about avoiding ambiguity, but in my opinion it is the price
to pay to be able to translate information into simple words from
English to non-European languages.  Although the Policy itself is not
going to be translated, I think that it can be advantageous if its
contents can be discussed in simple words in people's native languages.

Cheers,

-- Charles

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Russ Allbery]

Charles Plessy  writes:

> I disagree with this point of view.  In my own case I had to take a
> dictionary to learn what a stanza is, while the word paragraph is surely
> know at least to anybody who studied English in a classroom.

> In my own field, (molecular biology) we (or at least some of us) are
> putting some effort to eliminate jargon and use simple words that makes
> written documents more accessible to the public.  This is why I prefered
> paragraph to stanza when working on the specification.

This is a very valid point, and I appreciate you bringing this up!

My personal opinion is that I don't think jargon is necessarily good or
bad.  It has advantages and drawbacks.

One drawback that you're correctly pointing out is accessibility: jargon
can make things that would otherwise be comprehensible harder to
understand.  It can also be off-putting and alienating to people, and thus
make it harder for them to get involved in a shared project.

The advantage of jargon, and the reason why jargon exists and why humans
keep inventing it, is that it's precise.  You don't need as much context
to disambiguate what a sentence may be talking about.  I do find the use
of paragraph the way we were previously using it to be confusing,
particularly given that the paragraphs contain fields which in turn
contain actual paragraphs in the normal sense of the term.  In some
contexts, precision doesn't matter, but Debian Policy is one place where
we should try to be precise.

Stanza has the significant drawback that it's dictionary definition is
specific to poetry.  In poetry, it's a close analog to how we're using it,
but that does make it somewhat obscure.  It does have the minor advantage
of being terminology that was already in use for exactly this construction
in deb822 files.

I don't want to keep using paragraph, but I'd be open to some other term
that Guillem was also open to (I think matching the terminology in dpkg is
very important).  Section or block are commonly used for things like this,
but aren't very precise, so I'm not that enthused by them.

> If I were to redo such a specification from scratch, I would ask
> non-European language speakers their opinion too.

I'm definitely interested in that opinion from anyone who is listening in!

-- 
Russ Allbery (r...@debian.org)  

Bug#1020248: [Git][dbnpolicy/policy][master] 2 commits: Use stanza to refer to deb822 parts instead of paragraph

[Charles Plessy]

Hi all,

while I do not want to pull the handbrake I would like to add my
minority opinion to that change:

Le Tue, Sep 20, 2022 at 04:11:43PM +, Russ Allbery (@rra) a écrit :
> 
> The «stanza» name is a commonly used and understood term when referring
> to deb822 blocks. Although «paragraph» is commonly used it has the
> problem of being confusing as it then makes it hard to distinguish
> actual text paragraphs in prose, while «stanza» is a very specific
> term that is not applied anywhere else in the deb822 context, so its
> always more clear and specific.

I disagree with this point of view.  In my own case I had to take a
dictionary to learn what a stanza is, while the word paragraph is surely
know at least to anybody who studied English in a classroom.

In my own field, (molecular biology) we (or at least some of us) are
putting some effort to eliminate jargon and use simple words that makes
written documents more accessible to the public.  This is why I prefered
paragraph to stanza when working on the specification.

If I were to redo such a specification from scratch, I would ask
non-European language speakers their opinion too.

Have a nice day,

-- 
Charles