docutils-develop

[Docutils-develop] Name for new attribute

[Stefan M. <sm...@oe...>]

-----BEGIN PGP SIGNED MESSAGE-----

Hi!

Since David seems to be decided to introduce the unholy attribute
named ``class`` in HTML - could it get at least a correct name in
reST? Webster says:

  1.
     a. a body of students meeting regularly to study the same subject
     b. the period during which such a body meets
     c. a course of instruction
     d. a body of students or alumni whose year of graduation is the same

  2.
     a. a group sharing the same economic or social status <the working
	class>
     b. social rank; especially : high social rank
     c. high quality : ELEGANCE_

  3. a group, set, or kind sharing common attributes: as
     a. a major category in biological taxonomy ranking above the
        order and below the phylum or division
     b. a collection of adjacent and discrete or continuous values of
        a random variable
     c. SET_ 21

  4. a division or rating based on grade or quality

  5. the best of its kind <the class of the league>

Probably case 3 is most closely to the meaning intended in HTML here.
However, in HTML the class attribute has been created to represent
structural features simply not present in HTML and to have a hook CSS
can hook in.

As far as I understood this should not be the intended meaning in
reST. However, in reST it should be more like a hint or so for a
writer to create some special output style. If so could the attribute
be named that way then?

Ahm - prehaps it would be useful to explicitly think about the
intended meaning of such an attribute instead of simply copying the
meaning from HTML?

I can not come up with a really good suggestion though. Probably it's
better to leave that to the English native speakers anyway.


						Mit Freien Gr=FC=DFen

						Stefan

-----BEGIN PGP SIGNATURE-----
Version: 2.6.3in
Charset: noconv
Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface

iQCVAwUBPr4nsAnTZgC3zSk5AQFBcgP/WyaKOitSNnD2sbifK3wmc2wI81UURXDb
J9rad319OUP5sPermZaSQu2Na+SXBoY5aNCpqqWn6OQvPXotFd+XIGU5FJkSlLpW
lXL0+ysP3vByMhZ9km3SVQjN7wnhot//SLu6Z2NSeHMU5bkJI9DniS6ZqkpkKCeB
Dyns9sq/pOU=3D
=3DPWgq
-----END PGP SIGNATURE-----

Re: [Docutils-develop] Name for new attribute

[Aahz <aa...@py...>]

On Sun, May 11, 2003, Stefan Merten wrote:
>
> Since David seems to be decided to introduce the unholy attribute
> named ``class`` in HTML - could it get at least a correct name in
> reST? 

Why do you call it unholy?

>   3. a group, set, or kind sharing common attributes: as
>      a. a major category in biological taxonomy ranking above the
>         order and below the phylum or division
>      b. a collection of adjacent and discrete or continuous values of
>         a random variable
>      c. SET_ 21
> 
> Probably case 3 is most closely to the meaning intended in HTML here.
> However, in HTML the class attribute has been created to represent
> structural features simply not present in HTML and to have a hook CSS
> can hook in.

That's similar to the intent in reST, actually, though I'd disagree that
the HTML intent is for *structural* features -- it's for formatting
features.  (You specify the formatting by providing a structural hook,
but structure is not the focus.)

> As far as I understood this should not be the intended meaning in
> reST. However, in reST it should be more like a hint or so for a
> writer to create some special output style. If so could the attribute
> be named that way then?

That's exactly how it works in HTML, too.

> Ahm - prehaps it would be useful to explicitly think about the
> intended meaning of such an attribute instead of simply copying the
> meaning from HTML?

Based on my understanding of the intent, "class" works just fine.
"Type" and "group" would also work, but they're even more generic.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"In many ways, it's a dull language, borrowing solid old concepts from
many other languages & styles:  boring syntax, unsurprising semantics,
few automatic coercions, etc etc.  But that's one of the things I like
about it."  --Tim Peters on Python, 16 Sep 93

Re: [Docutils-develop] Name for new attribute

[Stefan M. <sm...@oe...>]

-----BEGIN PGP SIGNED MESSAGE-----

Hi!

4 hours ago Aahz wrote:
> On Sun, May 11, 2003, Stefan Merten wrote:
>> Since David seems to be decided to introduce the unholy attribute
>> named ``class`` in HTML - could it get at least a correct name in
>> reST?=20
>=20
> Why do you call it unholy?

Because you can do something like this:

  <p class=3D"h1">This is the header - disguised as a <b
  class=3D"i">paragraph (rendered in italics)</b></p>

  <p class=3D"l1">A list disguised as a paragraph</p>
  <table class=3D"p">A paragraph disguised as a table</table>

I think you get the idea.

In HTML you can see that this kind of misuse is done all the time.
Misuse of this sort is one of the reasons why the structural idea of
HTML today is more or less forgotten. Why open up that door in reST as
well? Instead I'd plead to fully understand which problem is to be
solved here. If it is that you should be able to do completely your
own thing in reST just as in HTML, then ``class`` is perfect IMHO.

>>   3. a group, set, or kind sharing common attributes: as
>>      a. a major category in biological taxonomy ranking above the
>>         order and below the phylum or division
>>      b. a collection of adjacent and discrete or continuous values of
>>         a random variable
>>      c. SET_ 21
>>=20
>> Probably case 3 is most closely to the meaning intended in HTML here.
>> However, in HTML the class attribute has been created to represent
>> structural features simply not present in HTML and to have a hook CSS
>> can hook in.
>=20
> That's similar to the intent in reST, actually, though I'd disagree tha=
t
> the HTML intent is for *structural* features -- it's for formatting
> features.  (You specify the formatting by providing a structural hook,
> but structure is not the focus.)

Thanks for making this point. Then it should be called ``format`` or
something like this.

>> As far as I understood this should not be the intended meaning in
>> reST. However, in reST it should be more like a hint or so for a
>> writer to create some special output style. If so could the attribute
>> be named that way then?
>=20
> That's exactly how it works in HTML, too.

It should be called ``format`` if this is the intended meaning.

>> Ahm - prehaps it would be useful to explicitly think about the
>> intended meaning of such an attribute instead of simply copying the
>> meaning from HTML?
>=20
> Based on my understanding of the intent, "class" works just fine.
> "Type" and "group" would also work, but they're even more generic.

You got my point: ``class`` is too generic IMHO. Something more
specific like ``format`` or ``style-class`` or something would be
better IMHO.

4 hours ago David Goodger wrote:
> Stefan Merten wrote:
>> Since David seems to be decided to introduce the unholy attribute
>> named ``class`` in HTML - could it get at least a correct name in
>> reST?
>=20
> No new attribute is being introduced.  The "class" attribute has been i=
n=20
> Docutils since before it was named "Docutils" (added on 2002-02-04 in=20
> revision 1.32 of=20
> <http://cvs.sf.net/cgi-bin/viewcvs.cgi/docstring/dps/spec/gpdi.dtd>).

Well, then my point is completely irrelevant again. Sorry, for
stealing you time once more. My stupidity seems to be rather
unlimited.

> A=20
> new *directive* is being introduced to set the "class" attribute.=20
> Unholy or not, I don't see any good reason to change the name.

May be in my stupidity I should better ask questions then. Why is
``class`` the best name? What do you think ``class`` describes? Has it
anything to do with one of the Webster definitions?

>> However, in reST it should be more like a hint or so for a
>> writer to create some special output style.
>=20
>  From the comments in spec/docutils.dtd: "`class` is used to transmit=20
> individuality information forward."

Oh how wonderful. May be only a non-native speaker is unable to see
that ``class`` is of course the best name to describe the purpose to
"transmit individuality information forward". I'm so sorry for
disturbing you wisdom with my totally irrelevant babbling.

>> Ahm - prehaps it would be useful to explicitly think about the
>> intended meaning of such an attribute instead of simply copying the
>> meaning from HTML?
>=20
> I think the name appropriately expresses the indended meaning.  I know=20
> of no other word that expresses that meaning better.

So you think that ``class`` is the best description for "transmit
individuality information forward". Ok, then. [Sticking to asking
questions...] Could you explain with which specific meaning of the
Webster definition this coincides? Sorry, I'm really to dumb to see
that alone.

>> I can not come up with a really good suggestion though. Probably it's
>> better to leave that to the English native speakers anyway.
>=20
> If anybody does, please let us know.  But it's probably too late to be=20
> making a change.

In my years and years of programming and making concepts for
programming tasks I learned one thing: The best thing you can have is
a good concept matching the thing you want to implement most closely.
For that you need to understand what you want to implement and in
cases like this find a name which transmits this meaning as good as
possible. The rest is writing this down in a formal language.

A bad concept easily haunts you for years and years. Believe me - I
know what I'm talking about... For a great thing like reStructuredText
containing a number of great concepts - actually that's why I'm here -
I'd really like to see only first class (sic!) concepts to be used.
However, my stupidity and dumbness based on my totally irrelevant
experience in some big software projects prevents me from seeing the
shining brightness of the wisdom. Sorry, that's obviously my fault.


						Mit Freien Gr=FC=DFen

						Stefan

PS: If you find some pieces of cynicism in this mail you may not be
totally wrong.

-----BEGIN PGP SIGNATURE-----
Version: 2.6.3in
Charset: noconv
Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface

iQCVAwUBPr6i5wnTZgC3zSk5AQHZHgP8DBKNMRGW2IXWjIKi5B4o9B3Ql5aWBPMt
Bgq55mCWUfKOjZQ5LrqYzjkSmPL8EvtClLHRHmu18noadXfDcajReJb3ci2rrXWw
GZzNcKh8I9ZpDSXSkyDwI6vDHXBj+kraEpeLSypDvvdpImeEq9nlAAdJnaFwr0m4
Qm9wwxWBgJI=3D
=3D3K0Y
-----END PGP SIGNATURE-----

Re: [Docutils-develop] Name for new attribute

[Aahz <aa...@py...>]

On Sun, May 11, 2003, Stefan Merten wrote:
> 4 hours ago Aahz wrote:
>> On Sun, May 11, 2003, Stefan Merten wrote:
>>>
>>> Since David seems to be decided to introduce the unholy attribute
>>> named ``class`` in HTML - could it get at least a correct name in
>>> reST? 
>> 
>> Why do you call it unholy?
> 
> Because you can do something like this:
> 
>   <p class="h1">This is the header - disguised as a <b
>   class="i">paragraph (rendered in italics)</b></p>
> 
>   <p class="l1">A list disguised as a paragraph</p>
>   <table class="p">A paragraph disguised as a table</table>
> 
> I think you get the idea.
> 
> In HTML you can see that this kind of misuse is done all the time.
> Misuse of this sort is one of the reasons why the structural idea of
> HTML today is more or less forgotten. Why open up that door in reST as
> well? Instead I'd plead to fully understand which problem is to be
> solved here. If it is that you should be able to do completely your
> own thing in reST just as in HTML, then ``class`` is perfect IMHO.

Ah.  Well, Pythonic practice is to trust the programmer.  You can do
unholy tricks like that in XML, too, if one wants to behave stupidly.
Despite the fact that the *effect* is formatting and formatting is the
primary purpose, calling it a "class" is intended to focus the user's
mind on grouping, and I think it serves admirably for that.

The problem is that reST's variety of input purposes and output formats
requires some form of paramterized formatting, but we prefer that people
not create new formats willy-nilly.  I suspect that as with Python
itself, community pressure will keep most misuses out of the mainstream.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"In many ways, it's a dull language, borrowing solid old concepts from
many other languages & styles:  boring syntax, unsurprising semantics,
few automatic coercions, etc etc.  But that's one of the things I like
about it."  --Tim Peters on Python, 16 Sep 93

Re: [Docutils-develop] Name for new attribute

[David G. <go...@py...>]

[Stefan Merten]
 > PS: If you find some pieces of cynicism in this mail you may not be
 > totally wrong.

I found it extremely snotty.  No need for that here.

[Stefan Merten]
 >>> Since David seems to be decided to introduce the unholy attribute
 >>> named ``class`` in HTML - could it get at least a correct name in
 >>> reST?

[Aahz]
 >> Why do you call it unholy?
 >
 > Because you can do something like this:
 >
 >   <p class="h1">This is the header - disguised as a <b
 >   class="i">paragraph (rendered in italics)</b></p>
 >
 >   <p class="l1">A list disguised as a paragraph</p>
 >   <table class="p">A paragraph disguised as a table</table>
 >
 > I think you get the idea.

That's simply abuse.  You cannot prevent abuse with a name change.
When the abuser realizes that the "variant" or "format" (or whatever)
attribute is translated to HTML "class", they'll abuse it anyway.

 > In HTML you can see that this kind of misuse is done all the time.
 > Misuse of this sort is one of the reasons why the structural idea of
 > HTML today is more or less forgotten. Why open up that door in reST as
 > well? Instead I'd plead to fully understand which problem is to be
 > solved here.

The problem to be solved here is that the document or application
author wants to tag a document element for later selection.  This
typically means they want to identify a variation of the document
element for special processing or formatting.  We want to add
functionality to allow this type of tagging/identification, so that
minor variations can be implemented without changes to the Docutils
code.

I think "class" is as good a term as any.  It's usage is identical to
that of "a constellation-class starship" or "first-class postage" or
"economy-class seat".  From my dictionary,

     1. a number of persons or things regarded as belonging together
     befcause of common attributes, qualities, or traits; kind; sort.
     ... 13. *Math.* a set; a collection.

 > It should be called ``format`` if this is the intended meaning.

"Format" is not the intended meaning.  The purpose of the attribute is
to indicate an "is-a" relationship, not "format-as".  So '<block_quote
class="epigraph">' means "this is an epigraph-class block quote".  It
doesn't specify any formatting; it implies "do with it as you will".
I recommend against format-specific use.

 > In my years and years of programming and making concepts for
 > programming tasks I learned one thing: The best thing you can have
 > is a good concept matching the thing you want to implement most
 > closely.  For that you need to understand what you want to implement
 > and in cases like this find a name which transmits this meaning as
 > good as possible.

I agree with this.  If you look back through the mailing list
archives, you'll see many examples where I've agonized over the naming
of something.  I didn't agonize over "class", probably because it fit
the idea well.

One thing I've learned over the years is that sarcasm, disrespect, and
a bad attitude are rarely beneficial in a discussion, especially a
technical discussion via email.  Such behavior usually results in bad
feelings all around, the perpetrator's ideas being dismissed, and the
perpetrator being added to people's kill-files.  Please stop.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

Re: [Docutils-develop] Name for new attribute

[David G. <go...@py...>]

Stefan Merten wrote:
> Since David seems to be decided to introduce the unholy attribute
> named ``class`` in HTML - could it get at least a correct name in
> reST?

No new attribute is being introduced.  The "class" attribute has been in 
Docutils since before it was named "Docutils" (added on 2002-02-04 in 
revision 1.32 of 
<http://cvs.sf.net/cgi-bin/viewcvs.cgi/docstring/dps/spec/gpdi.dtd>).  A 
new *directive* is being introduced to set the "class" attribute. 
Unholy or not, I don't see any good reason to change the name.

> However, in reST it should be more like a hint or so for a
> writer to create some special output style.

 From the comments in spec/docutils.dtd: "`class` is used to transmit 
individuality information forward."  In fact, I don't expect Writers to 
select on class attributes.  If possible, the attributes should be 
passed forward into the final renderer to interact with a stylesheet. 
Some formats may not support stylesheets, I know -- these formats should 
be able to ignore the class attributes or select on them, as they 
choose.  There's room for improvement there.

> Ahm - prehaps it would be useful to explicitly think about the
> intended meaning of such an attribute instead of simply copying the
> meaning from HTML?

I think the name appropriately expresses the indended meaning.  I know 
of no other word that expresses that meaning better.  And the precedent 
from HTML is not a problem -- we don't need "not invented here" syndrome 
in Docutils.

> I can not come up with a really good suggestion though. Probably it's
> better to leave that to the English native speakers anyway.

If anybody does, please let us know.  But it's probably too late to be 
making a change.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv