classes, block, etc.

[Bruce_D_Arcus1]

So Frank has added a patch that essentially reflects what’s in this
test to support styles like AAA:

http://bitbucket.org/fbennett/citeproc-js/src/tip/std/humans/class_AaaSample.txt

Here’s the key portion:

I’m still unclear what these classes add. For example, why wouldn’t
this work equally well?

Note: I know that in this case csl inline-block != css inline-block,
and we’d need to describe how to render this. But that aside, is there
any particular value added to using class names?

Not trying to be difficult; just trying to understand, and to limit
unnecessary changes.

Bruce

[Frank_Bennett]

Certainly understand the desire to keep changes to a minimum. For
what it’s worth, the patch is backward compatible; the only thing that
it drops is “inline-block”, which isn’t currently used by any styles
in the repository.

Currently, “block” and “linline-block” are token values for the
display= attribute, so in your example, names would have
display=“block”, and the group would have display=“inline-block”. The
display attribute is a general formatting option, so it could be moved
from the group to the title text element.

In the AAA style, the year + year-suffix portion of the cite are meant
to be treated as a unit of uniform width throughout the bibliography,
so those two elements need to be grouped. The example would then look
like this:

 <layout>
  <names variable="author" display="block">
    <name and="text"/>
  </names>
  <group>
    <date variable="issued">
      <date-part name="year"/>
    </date>
    <text variable="year-suffix"/>
  </group>
  <text variable="title" display="inline-block"/>
</layout>

Some attribute would be required on the bare group, to tell the
processor that the grouped text should be of a fixed width. That’s
what the “csl-left-label” class does in the class-based layout.

Another difficult problem that would follow from using
display=“block|inline-block” without any other changes is that
display=“block” is also used for annotation blocks in annotated
bibliographies. If styling is applied to the output from CSL using
classes (which I think everyone agrees would be desirable), then
headings and annotation blocks would need to be assigned different
class attributes in the output. That’s what the "csl-entry-heading"
and “csl-block-indent” classes enable.

I’ve probably made enough noise about this one now. Maybe someone
else has comments (Rintze, Sean, Dan, Simon, Richard, Jimmy, Robert,
Fergus if you’re listening)?

Frank

[Bruce_D_Arcus1]

I’m still unclear what these classes add. For example, why wouldn’t
this work equally well?

Certainly understand the desire to keep changes to a minimum. For
what it’s worth, the patch is backward compatible; the only thing that
it drops is “inline-block”, which isn’t currently used by any styles
in the repository.

Currently, “block” and “linline-block” are token values for the
display= attribute, so in your example, names would have
display=“block”, and the group would have display=“inline-block”. The
display attribute is a general formatting option, so it could be moved
from the group to the title text element.

In the AAA style, the year + year-suffix portion of the cite are meant
to be treated as a unit of uniform width throughout the bibliography,
so those two elements need to be grouped. The example would then look
like this:

<layout>
 <names variable="author" display="block">
   <name and="text"/>
 </names>
 <group>
   <date variable="issued">
     <date-part name="year"/>
   </date>
   <text variable="year-suffix"/>
 </group>
 <text variable="title" display="inline-block"/>

Some attribute would be required on the bare group, to tell the
processor that the grouped text should be of a fixed width. That’s
what the “csl-left-label” class does in the class-based layout.

For the AAA case, another way to put this is to say that the
inline-blocks should be aligned?

I presume that’s the more important point, and that the fixed-width
character of the preceding content (the label) is a consequence of
that?

Another difficult problem that would follow from using
display=“block|inline-block” without any other changes is that
display=“block” is also used for annotation blocks in annotated
bibliographies.

How is that a problem on the rendering end?

If styling is applied to the output from CSL using
classes (which I think everyone agrees would be desirable), then
headings and annotation blocks would need to be assigned different
class attributes in the output. That’s what the “csl-entry-heading”
and “csl-block-indent” classes enable.

You seem to collapsing semantics and rendering, and this is why I’m
getting confused.

In my implementation (at least as far as I’ve gotten), I derive the
semantics from the data, encode it in RDFa, and deal with the
rendering separately.

When we’re dealing with word-processor integration, am assuming one
can do something vaguely similar, but am not really sure.

I’ve probably made enough noise about this one now. Maybe someone
else has comments (Rintze, Sean, Dan, Simon, Richard, Jimmy, Robert,
Fergus if you’re listening)?

Yeah, I’d really appreciate other people taking a look at this. This
is the final push for 1.0, and it would help if others can pitch in to
resolve these remaining issues.

Bruce

[Rintze_Zelle]

I’m still unclear what these classes add. For example, why wouldn’t
this work equally well?

So I guess that when inline-blocks are aligned, Frank’s correction isn’t
necessary (the ‘group’-element wouldn’t add additional rendering info).

Another difficult problem that would follow from using
display=“block|inline-block” without any other changes is that
display=“block” is also used for annotation blocks in annotated
bibliographies.

How is that a problem on the rendering end?

What I don’t really see in the example above, though, is how the distinction
is made between the rendering of the “csl-entry-heading” (which should align
left) and of “csl-block-indent” (annotations, abstracts, which should be
indented), if both are specified with ‘block=“true”’. Does the rendering
follow implicitly from the order of elements? I.e. if the first output
element/group has ‘block’ set to true, it will be displayed as a header
(align left), while for all other instances the indented block alignment
will be used?

Rintze

[Bruce_D_Arcus1]

I’m still unclear what these classes add. For example, why wouldn’t
this work equally well?

So I guess that when inline-blocks are aligned, Frank’s correction
isn’t necessary (the ‘group’-element wouldn’t add additional
rendering info).

Another difficult problem that would follow from using
display=“block|inline-block” without any other changes is that
display=“block” is also used for annotation blocks in annotated
bibliographies.

How is that a problem on the rendering end?

What I don’t really see in the example above, though, is how the
distinction is made between the rendering of the “csl-entry-
heading” (which should align left) and of “csl-block-
indent” (annotations, abstracts, which should be indented), if both
are specified with ‘block=“true”’. Does the rendering follow
implicitly from the order of elements?

Yes.

I.e. if the first output element/group has ‘block’ set to true, it
will be displayed as a header (align left), while for all other
instances the indented block alignment will be used?

Why indented?

[Rintze_Zelle]

I.e. if the first output element/group has ‘block’ set to true, it will be
displayed as a header (align left), while for all other instances the
indented block alignment will be used?

Why indented?

I just wanted to confirm that the header and annotation blocks have
different layouts/alignments (see Frank’s examples at
gsl-nagoya-u.net - This website is for sale! - gsl nagoya u Resources and Information.), as I wasn’t
sure how these different roles of block were assigned.

Rintze

[Bruce_D_Arcus1]

Maybe …

…?

Bruce

[Frank_Bennett]

I’m still unclear what these classes add. For example, why wouldn’t
this work equally well?

Certainly understand the desire to keep changes to a minimum. For
what it’s worth, the patch is backward compatible; the only thing that
it drops is “inline-block”, which isn’t currently used by any styles
in the repository.

Currently, “block” and “linline-block” are token values for the
display= attribute, so in your example, names would have
display=“block”, and the group would have display=“inline-block”. The
display attribute is a general formatting option, so it could be moved
from the group to the title text element.

In the AAA style, the year + year-suffix portion of the cite are meant
to be treated as a unit of uniform width throughout the bibliography,
so those two elements need to be grouped. The example would then look
like this:

<layout>
 <names variable="author" display="block">
   <name and="text"/>
 </names>
 <group>
   <date variable="issued">
     <date-part name="year"/>
   </date>
   <text variable="year-suffix"/>
 </group>
 <text variable="title" display="inline-block"/>

Some attribute would be required on the bare group, to tell the
processor that the grouped text should be of a fixed width. That’s
what the “csl-left-label” class does in the class-based layout.

For the AAA case, another way to put this is to say that the
inline-blocks should be aligned?

I presume that’s the more important point, and that the fixed-width
character of the preceding content (the label) is a consequence of
that?

Yes. So could this be marked with something like display=“label”?

[Bruce_D_Arcus1]

…

I presume that’s the more important point, and that the fixed-width
character of the preceding content (the label) is a consequence of
that?

Yes. So could this be marked with something like display=“label”?

What rendering would that trigger?

Bruce

[Frank_Bennett]

…

I presume that’s the more important point, and that the fixed-width
character of the preceding content (the label) is a consequence of
that?

Yes. So could this be marked with something like display=“label”?

What rendering would that trigger?

A label should float to the left of an inline-block that follows it,
and should have the same width as other labels in the bibliography.

[Bruce_D_Arcus1]

So it should have a negative indent?

OK, so let’s try to break this down in ways that we can feed into the spec.

The display logic of CSL is based on a small subset of CSS [ref
http://www.w3.org/TR/CSS2/visuren.html#display-prop]. The normal
display rule is that a content node is rendered inline. Exceptions can
be configured using the “display” attribute, which includes the
following options:

1. block: this causes a content node to render as a block separate
   from the main item content. For example, if one wanted to have an
   annotation note on a separate line for an annotated bibliography, one
   could assign this display value to a “annote” cs:text node.

2. inline-block: this causes a content node to render as a block
   inserted into the item block. Effectively, this will shift the margin
   for flowed content to align with the first line of this node. [ this
   is HARD to explain; also, need an example]

OK, now we have this indenting problem. Labels may need to be negative
indented, and other content, including inline-blocks, may need to get
positively indented in complex ways (alignment and such). I have
suggested:

3. indent: when coupled with block or inline-block, indents the content

So the problem: it’s too vague; we don’t say how much to indent, nor
allow it to be configured.

If we add the ability to specify a value (including a negative value),
then we’re stuck with defining what those values should be.

One simple strawman of an idea:

<cs:text macro=“author” display=“block” indent="-1"/>

So this would put the author macro content effectively as a negative
indented heading.

The obvious question, though, is what the hell does “1” mean; what’s the unit?

I suggest if we agree on this approach, we just choose something (say
em) and settle on it.

Still need to address the aligned inline block thing though.

Note: I think whether we used class names or do it as I’m suggesting
here, the problem is the same; we have to define how the rendering
gets configured.

Bruce

[Frank_Bennett]

I presume that’s the more important point, and that the fixed-width
character of the preceding content (the label) is a consequence of
that?

Yes. So could this be marked with something like display=“label”?

What rendering would that trigger?

A label should float to the left of an inline-block that follows it,
and should have the same width as other labels in the bibliography.

So it should have a negative indent?

No. Not in CSS, at least. A negative indent of an inline element
would align a column of such elements on their right edge, which would
be wrong for labels.

But the choice between “indent” and “float” is an implementation
detail, which may vary between output languages. Currently, Zotero’s
CSL processor does second-field-align as a table in HTML, and as a
list of labels with block-tab indents in RTF. CSL doesn’t need to
know anything about that choice. But CSL does need to be able to
describe the elements of the layout to the client’s rendering engine.

I’ve already boiled down what’s needed for that description.
Bibliography layouts can be described with four elements. I’ve called
them “heading”, “left-label”, “item” and “block-indent”. They don’t
have to be called by those particular names in CSL, and they don’t
need to be assigned through a class= attribute. But there must be a
minimum of four different layout elements, and it should not be
exceptionally difficult to assign portions of the output to them.

Any solution should be supported, at minimum, by worked examples of
how CSL elements are mapped to each of the four parts of a layout, as
I have done here:

gsl-nagoya-u.net - This website is for sale! - gsl nagoya u Resources and Information.

OK, so let’s try to break this down in ways that we can feed into the spec.

The display logic of CSL is based on a small subset of CSS [ref
Visual formatting model]. The normal
display rule is that a content node is rendered inline. Exceptions can
be configured using the “display” attribute, which includes the
following options:

1. block: this causes a content node to render as a block separate
   from the main item content. For example, if one wanted to have an
   annotation note on a separate line for an annotated bibliography, one
   could assign this display value to a “annote” cs:text node.

2. inline-block: this causes a content node to render as a block
   inserted into the item block. Effectively, this will shift the margin
   for flowed content to align with the first line of this node. [ this
   is HARD to explain; also, need an example]

We run into this in comparative law a lot, actually, where concepts
from different legal systems have similar functions and the same name,
but slightly different meanings (“mortgage”, “heirs”, “trust”). It’s
an endless source of confusion, caused by overcrowding in the
namespace. We’re not bound by the constraints of legal tradition
here. If it works differently, we can and should call it something
different, to reduce the potential for confusion.

The original CSS inline-block display property only has meaning when
applied to elements that have a fixed width. It’s used to produce
flowed layouts composed of boxes containing their own formatted
content, like this:

gsl-nagoya-u.net - This website is for sale! - gsl nagoya...

A CSS inline-block MUST be assigned a fixed width, or it will behave
exactly like a normal block, and consume all available horizontal
space. What you are calling an “inline-block” above is something
else. In CSS terms, it’s just an ordinary block, indented by a
specified amount. To create it, you need to know the indent
dimension.

OK, now we have this indenting problem. Labels may need to be negative
indented, and other content, including inline-blocks, may need to get
positively indented in complex ways (alignment and such). I have
suggested:

3. indent: when coupled with block or inline-block, indents the content

So the problem: it’s too vague; we don’t say how much to indent, nor
allow it to be configured.

It’s only vague if you assume that the CSL markup needs to say
something about this dimension. But it hasn’t done so in the past,
and it needn’t do so here.

CSL can’t know specific dimensions, because it doesn’t know the sizes
of the fonts involved. What it can do, though (and what it already
does in the Zotero implementation for RTF output, I believe) is to
measure the maximum number of characters in the label, and pass that
through to the calling application, separately from the output
strings. The max-width number is then used by the calling application
to compose a class description, which it will apply to the four
elements out of which the layout is composed.

If we add the ability to specify a value (including a negative value),
then we’re stuck with defining what those values should be.

As outlined above, we don’t need to do that.

[Bruce_D_Arcus1]

Alright, the main issue I have with your current proposal is the
"item" language. I think that will be a source of confusion. What if,
for example, someone wants this content block-indented?

Can you think of names that would clear this up?

Am a little worried about the “label” one too. Would it be wrong to
call it just “left-margin”?

[Bruce_D_Arcus1]

So just extending this, what happens if we have a style that includes
this (assuming am using “display” in lieu of “class”, and allowing it
everywhere)?

So what does “indent” here mean? Do the last two nodes get right
aligned, or is the second indented WRT to the first (which might be
required for AAA?)?

If the former, then are you essentially assuming a formatting grid like …

[ ------ label -----] [----------------- item (maybe let’s call it
"body"?) ----------------]
[------------------------ indent
------------------------------------]

…? If the latter, then we need to explain what “indent” is relative
to (which could get hairy).

In any case, I’d prefer if the descriptors all be consistently
presentational; maybe “left-margin”, “body” and “block” and “indent”
(well, these last two need not be split , I guess, if we assume the
first reading of indent above; could just have multiple “body” nodes
to get the same thing)?

Getting to the actual patch, the language just needs to be tightened
up. For example, you describe the label as:

•          ## Text to be used as a label for the citation entry,
  

•          ## typically floated into the left margin.
  

That “typically” qualifier is a problem. We need to say definitively
how it IS rendered (including how it’s aligned).

As for your comment about not knowing font sizes and such, that’s
irrelevant if you’re dealing with ems (which scale depending on
font-size). I’d rather not have to deal with this part at all, but I
can just see this coming up at some point (user on forum says “my bib
entries are indented too much”).

Bruce

[Frank_Bennett]

Alright, the main issue I have with your current proposal is the “item”
language. I think that will be a source of confusion. What if, for example,
someone wants this content block-indented?

Can you think of names that would clear this up?

Am a little worried about the “label” one too. Would it be wrong to call it
just “left-margin”?

So just extending this, what happens if we have a style that includes
this (assuming am using “display” in lieu of “class”, and allowing it
everywhere)?

So what does “indent” here mean? Do the last two nodes get right
aligned, or is the second indented WRT to the first (which might be
required for AAA?)?

If the former, then are you essentially assuming a formatting grid like …

[ ------ label -----] [----------------- item (maybe let’s call it
“body”?) ----------------]
[------------------------ indent
------------------------------------]

…? If the latter, then we need to explain what “indent” is relative
to (which could get hairy).

In any case, I’d prefer if the descriptors all be consistently
presentational; maybe “left-margin”, “body” and “block” and “indent”
(well, these last two need not be split , I guess, if we assume the
first reading of indent above; could just have multiple “body” nodes
to get the same thing)?

Getting to the actual patch, the language just needs to be tightened
up. For example, you describe the label as:

•          ## Text to be used as a label for the citation entry,
  

•          ## typically floated into the left margin.
  

That “typically” qualifier is a problem. We need to say definitively
how it IS rendered (including how it’s aligned).

This is all sounding really good. I’ll take some time to mull things
over before responding, but just on these final points:

As for your comment about not knowing font sizes and such, that’s
irrelevant if you’re dealing with ems (which scale depending on
font-size).

True, but the variable value to be determined is still the same
(max-number-of-characters * 1em = width). Once the max character
width is known, I guess the math could be done on either side of the
connection (CSL processor or client).

I’d rather not have to deal with this part at all, but I
can just see this coming up at some point (user on forum says “my bib
entries are indented too much”).

If classes can be made to transfer smoothly into the client, they
would come into play on this one – for a word processor, the user
could be told to adjust the style applied to the appropriate part of
the layout, and there wouldn’t be any need to touch the CSL.

[Frank_Bennett]

Alright, the main issue I have with your current proposal is the “item”
language. I think that will be a source of confusion. What if, for
example,
someone wants this content block-indented?

Can you think of names that would clear this up?

Am a little worried about the “label” one too. Would it be wrong to call
it
just “left-margin”?

So just extending this, what happens if we have a style that includes
this (assuming am using “display” in lieu of “class”, and allowing it
everywhere)?

I agree that display= is more appropriate than class=.

So what does “indent” here mean? Do the last two nodes get right
aligned, or is the second indented WRT to the first (which might be
required for AAA?)?

I’m not sure what you mean here by “right aligned”. The layout of the
illustration below got broken in the mail, and I’ve been unable to
reconstruct it.

But blocks that are indented should not cascade (I can’t think of a use case
for cascading, but I guess you could get that effect by nesting them). The
indent amount itself can be some arbitrary length. Users and their
publishers will each have their own idiosyncratic design preferences, and
it’s enough if CSL provides a rough approximation of their desired format,
and enables them to control the layout with a minimum of effort.

I discovered today that CSL already follows this principle; one of the test
fixtures attempted to assign line-spacing=“1.5”, and the validator rejected
the floating-point value, because only integers are recognized. On
reflection, I realized that that is right; single- or double-spacing gets
the layout into the ballpark, and the fine tuning can be handled by tweaking
the classes that make up the layout.

If the former, then are you essentially assuming a formatting grid like
…

[ ------ label -----] [----------------- item (maybe let’s call it
“body”?) ----------------]
[------------------------ indent
------------------------------------]

…? If the latter, then we need to explain what “indent” is relative
to (which could get hairy).

In any case, I’d prefer if the descriptors all be consistently
presentational; maybe “left-margin”, “body” and “block” and “indent”
(well, these last two need not be split , I guess, if we assume the
first reading of indent above; could just have multiple “body” nodes
to get the same thing)?

The naming looks good to me, especially if we can keep both “block” and
“indent”.

Getting to the actual patch, the language just needs to be tightened
up. For example, you describe the label as:

•          ## Text to be used as a label for the citation entry,
  

•          ## typically floated into the left margin.
  

That “typically” qualifier is a problem. We need to say definitively
how it IS rendered (including how it’s aligned).

I’ll work on this some more.On Mon, Aug 10, 2009 at 8:55 AM, Bruce D’Arcus<@Bruce_D_Arcus1> wrote:

On Sun, Aug 9, 2009 at 6:44 PM, Bruce D’Arcus<@Bruce_D_Arcus1> wrote:

As for your comment about not knowing font sizes and such, that’s
irrelevant if you’re dealing with ems (which scale depending on
font-size). I’d rather not have to deal with this part at all, but I
can just see this coming up at some point (user on forum says “my bib
entries are indented too much”).

Bruce

---

Let Crystal Reports handle the reporting - Free Crystal Reports 2008
30-Day
trial. Simplify your report design, integration and deployment - and focus
on

[Bruce_D_Arcus1]

I’m not sure what you mean here by “right aligned”. The layout of the
illustration below got broken in the mail, and I’ve been unable to
reconstruct it.

But blocks that are indented should not cascade (I can’t think of a use case
for cascading, but I guess you could get that effect by nesting them).

Right; that’s what I was asking.

The indent amount itself can be some arbitrary length. Users and their
publishers will each have their own idiosyncratic design preferences, and
it’s enough if CSL provides a rough approximation of their desired format,
and enables them to control the layout with a minimum of effort.

OK.

I discovered today that CSL already follows this principle; one of the test
fixtures attempted to assign line-spacing=“1.5”, and the validator rejected
the floating-point value, because only integers are recognized. On
reflection, I realized that that is right; single- or double-spacing gets
the layout into the ballpark, and the fine tuning can be handled by tweaking
the classes that make up the layout.

OK.

The naming looks good to me, especially if we can keep both “block” and
“indent”.

So …

attribute display { “left-margin”, “body”, “block”, “indent” }

…?

Is “body” the default? E.g. what happens if you have a style that
doesn’t need some special label handling (which is most of them)?

Getting to the actual patch, the language just needs to be tightened
up. For example, you describe the label as:

•          ## Text to be used as a label for the citation entry,
  

•          ## typically floated into the left margin.
  

That “typically” qualifier is a problem. We need to say definitively
how it IS rendered (including how it’s aligned).

I’ll work on this some more.

OK.

Bruce

[Bruce_D_Arcus1]

Ahem …On Mon, Aug 10, 2009 at 7:33 AM, Bruce D’Arcus<@Bruce_D_Arcus1> wrote:

So …

attribute display { “left-margin”, “body”, “block”, “indent” }

attribute display { “left-margin” | “body” | “block” | “indent” }

Bruce

[Frank_Bennett]

I’m not sure what you mean here by “right aligned”. The layout of the
illustration below got broken in the mail, and I’ve been unable to
reconstruct it.

But blocks that are indented should not cascade (I can’t think of a use case
for cascading, but I guess you could get that effect by nesting them).

Right; that’s what I was asking.

The indent amount itself can be some arbitrary length. Users and their
publishers will each have their own idiosyncratic design preferences, and
it’s enough if CSL provides a rough approximation of their desired format,
and enables them to control the layout with a minimum of effort.

OK.

I discovered today that CSL already follows this principle; one of the test
fixtures attempted to assign line-spacing=“1.5”, and the validator rejected
the floating-point value, because only integers are recognized. On
reflection, I realized that that is right; single- or double-spacing gets
the layout into the ballpark, and the fine tuning can be handled by tweaking
the classes that make up the layout.

OK.

The naming looks good to me, especially if we can keep both “block” and
“indent”.

So …

attribute display { “left-margin”, “body”, “block”, “indent” }

…?

Is “body” the default? E.g. what happens if you have a style that
doesn’t need some special label handling (which is most of them)?

There will be an implicit enclosing block wrapper for each entry (an
unsung and unseen fifth class – like the Fifth Beatle!). Unadorned
elements will render inline, margin-to-margin, inside that block, and
it will provide the top and bottom spacing around each entry,
regardless of other markup.