docbook-apps

RE: [docbook-apps] should simplesect be chunked?Hi,
I don't think section level is the right criterium for excluding simplesect from chunking. A chapter can contain nothing but simplesect elements, making them equivalent to level1 sections. Currently such a chapter would be a single chunk, even if each simplesect was long, leading to a very long chunk. Also, in the chunking stylesheets, the level of section chunking is controlled by a stylesheet parameter.

So you could have one chapter consisting of simplesects that is are not chunked, and another chapter consisting of single-level section elements, and only the latter chapter will be chunked. Since simplesect is essentially a terminal section, that isn't the behavior I would expect. Readers certainly won't know the difference.

The DTD defines a simplesect as identical to section except for its lack of section children, as well as not allowing index, glossary, and bibliography. That sounds the same as all the terminal section elements that I write. So I don't see why they are processing differently from terminal sections.

I was also surprised to see that simplesect does not get numbered when section.autolabel is turned on. That makes no sense to me, and I think it is a bug. The template with match="simplesect" mode="label.markup" in common/labels.xsl has code written to generate a number label for it. I would have to dig deeper to see why it doesn't work.


Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message -----
From: Johnson, Eric
To: Dave Pawson ; Bob Stayton
Cc: DocBook Apps
Sent: Monday, September 15, 2008 4:51 AM
Subject: RE: [docbook-apps] should simplesect be chunked?


I was thinking the same thing as Dave.
Technically, I see no reason not make simplesect chunkable. However, I think, in most cases, the resulting HTML content would be too small to be a standalone page.
I guess there are use cases where chunking that low would be appropriate.

-----Original Message-----
From: Dave Pawson [mailto:davep@dpawson.co.uk]
Sent: Mon 9/15/2008 2:18 AM
To: Bob Stayton
Cc: DocBook Apps
Subject: Re: [docbook-apps] should simplesect be chunked?

Bob Stayton wrote:
> While reviewing a stylesheet bug, I also noticed that the simplesect
> element is not chunked. That seems odd to me, since a simplesect is a
> real section, except that it cannot have child sections. Does anyone
> see a problem with making simplesect into chunks?


Only that it seems intuitively wrong to chunk at such a low level?




regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

On Mon, Sep 15, 2008 at 10:15 AM, Bob Stayton <bobs@sagehill.net> wrote:
> I don't think section level is the right criterium for excluding simplesect
> from chunking. A chapter can contain nothing but simplesect elements,
> making them equivalent to level1 sections. Currently such a chapter would
> be a single chunk, even if each simplesect was long, leading to a very long
> chunk.

Right, hence my concern.

> Also, in the chunking stylesheets, the level of section chunking is
> controlled by a stylesheet parameter.

Yup.

> The DTD defines a simplesect as identical to section except for its lack of
> section children, as well as not allowing index, glossary, and
> bibliography. That sounds the same as all the terminal section elements
> that I write. So I don't see why they are processing differently from
> terminal sections.

I agree.

> I was also surprised to see that simplesect does not get numbered when
> section.autolabel is turned on. That makes no sense to me, and I think it
> is a bug. The template with match="simplesect" mode="label.markup" in
> common/labels.xsl has code written to generate a number label for it. I
> would have to dig deeper to see why it doesn't work.

+1


Thanks,
Keith

Bob Stayton wrote:
> Hi,
> I don't think section level is the right criterium for excluding
> simplesect from chunking. A chapter can contain nothing but simplesect
> elements, making them equivalent to level1 sections. Currently such a
> chapter would be a single chunk, even if each simplesect was long,
> leading to a very long chunk. Also, in the chunking stylesheets, the
> level of section chunking is controlled by a stylesheet parameter.
>
> So you could have one chapter consisting of simplesects that is are not
> chunked, and another chapter consisting of single-level section
> elements, and only the latter chapter will be chunked.


Too many what-if's there Bob. We can all make daft decisions
when marking up.

For Docbook, used sensibly, there's no need to chunk at simplesect level
IMHO.



regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Bob,
I do not disagree with your position in theory. I can see where there
may be style guides that use simplesect in such a way as they would be
long enough to warrant entire html pages.

I don't think that having simplesect blocks being that long makes much
sense however. We use simplesect as the only terminal section element.
It is, in information mapping terms, a block. So a chapter would never
only have sect1 elements breaking it up into sections. Such a chapter
would use simplesect. If the simplesect blocks get big enough to warrant
it, then the chapter would need to be broken up into sections - each of
which contains a group of simplesect element. sect1-sect5 elements and
section elements are not used as terminal sections.

Since this is only one way of doing the mark-up using docbook and others
will likely disagree with this approach, I don't think adding the
capabilities to chunk simplesect is a bad idea.

Perhaps simplesect chunking should have its own parameter for being
turned on and off? That way people whose output depends on the current
chunking algorithm for sections won't be messed up.

Cheers,
Eric

-----Original Message-----
From: Dave Pawson [mailto:davep@dpawson.co.uk]
Sent: Monday, September 15, 2008 1:54 PM
To: Bob Stayton
Cc: DocBook Apps
Subject: Re: [docbook-apps] should simplesect be chunked?

Bob Stayton wrote:
> Hi,
> I don't think section level is the right criterium for excluding
> simplesect from chunking. A chapter can contain nothing but
> simplesect elements, making them equivalent to level1 sections.
> Currently such a chapter would be a single chunk, even if each
> simplesect was long, leading to a very long chunk. Also, in the
> chunking stylesheets, the level of section chunking is controlled by a
stylesheet parameter.
>
> So you could have one chapter consisting of simplesects that is are
> not chunked, and another chapter consisting of single-level section
> elements, and only the latter chapter will be chunked.


Too many what-if's there Bob. We can all make daft decisions when
marking up.

For Docbook, used sensibly, there's no need to chunk at simplesect level
IMHO.



regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

I had noticed that simplesects don't chunk a while back when some of our
writers wanted a way to create sections that don't chunk and simplesect
seemed a possible answer. I was worried though that it was a bug that
would be fixed someday :-) So I implemented to
let writers control where chunking stops and that's now part of the
xsls.

I don't have strong feelings about simplesects chunking since we use the
processing instruction. I can obviously understand the need for giving
writers the option of creating sections that don't chunk. I do think
that either simplescts should chunk or "The Definitive Guide" should be
updated to indicate that the processing expectation is that they don't
chunk (or it should be parameterized). The current processing
instruction will stop the chunking of simplesects too btw.

David


> -----Original Message-----
> From: Johnson, Eric [mailto:Eric.Johnson@iona.com]
> Sent: Monday, September 15, 2008 1:28 PM
> To: docbook-apps
> Subject: RE: [docbook-apps] should simplesect be chunked?
>
> Bob,
> I do not disagree with your position in theory. I can see
> where there may be style guides that use simplesect in such a
> way as they would be long enough to warrant entire html pages.
>
> I don't think that having simplesect blocks being that long
> makes much sense however. We use simplesect as the only
> terminal section element.
> It is, in information mapping terms, a block. So a chapter
> would never only have sect1 elements breaking it up into
> sections. Such a chapter would use simplesect. If the
> simplesect blocks get big enough to warrant it, then the
> chapter would need to be broken up into sections - each of
> which contains a group of simplesect element. sect1-sect5
> elements and section elements are not used as terminal sections.
>
> Since this is only one way of doing the mark-up using docbook
> and others will likely disagree with this approach, I don't
> think adding the capabilities to chunk simplesect is a bad idea.
>
> Perhaps simplesect chunking should have its own parameter for
> being turned on and off? That way people whose output depends
> on the current chunking algorithm for sections won't be messed up.
>
> Cheers,
> Eric
>
> -----Original Message-----
> From: Dave Pawson [mailto:davep@dpawson.co.uk]
> Sent: Monday, September 15, 2008 1:54 PM
> To: Bob Stayton
> Cc: DocBook Apps
> Subject: Re: [docbook-apps] should simplesect be chunked?
>
> Bob Stayton wrote:
> > Hi,
> > I don't think section level is the right criterium for excluding
> > simplesect from chunking. A chapter can contain nothing but
> > simplesect elements, making them equivalent to level1 sections.
> > Currently such a chapter would be a single chunk, even if each
> > simplesect was long, leading to a very long chunk. Also, in the
> > chunking stylesheets, the level of section chunking is
> controlled by a
> stylesheet parameter.
> >
> > So you could have one chapter consisting of simplesects that is are
> > not chunked, and another chapter consisting of single-level section
> > elements, and only the latter chapter will be chunked.
>
>
> Too many what-if's there Bob. We can all make daft decisions
> when marking up.
>
> For Docbook, used sensibly, there's no need to chunk at
> simplesect level IMHO.
>
>
>
> regards
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail:
> docbook-apps-help@lists.oasis-open.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail:
> docbook-apps-help@lists.oasis-open.org
>
>