should I use section or sect1, sect2, sect3 etc?

Hello,

I'm somehow confused on whether I should use nested
<section> tags, or the
"predefined" <sect1> to <sect5>.
Are there any benefits in using the latter? Are there any
reasons why one
way should be avoided in certain situations?

Thanks in advance!
-- 
View this message in context: http://www.nab
ble.com/should-I-use-section-or-sect1%2C-sect2%2C-sect3-etc-
-tf3570509.html#a9975240
Sent from the docbook General mailing list archive at
Nabble.com.


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Rock Lobster wrote:
> 
> I'm somehow confused on whether I should use nested
<section> tags, or the
> "predefined" <sect1> to <sect5>.
> Are there any benefits in using the latter? Are there
any reasons why one
> way should be avoided in certain situations?

DocBook is all about semantic markup.  If your document has
a fixed 
nesting structure, you should express that in the document. 
If sections 
are less formal, use the generic tag.  Take a reference
manual, for 
example: you could lay down a rule that says that the
chapter 
introductions are always at level 1, followed by the main
topics of that 
chapter at level 2, and any subtopics at level 3.  You're
expressing the 
strict hierarchical nature of your document in the markup,
and that's a 
good thing.

If it's constructed with semantic markup in mind, you should
be able to 
look at a DocBook document and get a pretty good idea of
what sort of 
document it is just from the tags it uses.

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

I usually recommend using nested <section>. It makes
it easier to reuse 
content in different contexts if you need to.

For example, the same section may be reused in multiple
documents, but 
one of your documents may add another sectioning level above
that reuse. 
If you use the hard-coded levels, you may not be allowed to
use the 
original sect2 inside the new document's sect3. If you
consistently use 
section, then you can nest them freely.

Best regards,

--Scott

Rock Lobster wrote:
> Hello,
> 
> I'm somehow confused on whether I should use nested
<section> tags, or the
> "predefined" <sect1> to <sect5>.
> Are there any benefits in using the latter? Are there
any reasons why one
> way should be avoided in certain situations?
> 
> Thanks in advance!

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Scott Hudson wrote:
> I usually recommend using nested <section>. It
makes it easier to reuse 
> content in different contexts if you need to.

That lack of context is also a disadvantage.  It means you
can't look at 
a section of the document and immediately tell where it fits
in 
logically with the rest of the structure.

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

On Fri, 13 Apr 2007 01:56:26 -0700 (PDT), Rock Lobster  
<emailchristian-gleinser.de> wrote:

> I'm somehow confused on whether I should use nested
<section> tags, or  
> the
> "predefined" <sect1> to <sect5>.
> Are there any benefits in using the latter? Are there
any reasons why one
> way should be avoided in certain situations?

Using <sect1>, etc. makes a document harder to
maintain. You cannot move a  
section at a higher or lower level, and it makes components
less reusable  
(because it implies a strict level in a document tree). BTW,
by default  
XXE uses <section> instead of <sectX>. The only
benefits of explicit  
section levels is maybe it makes parsing for conversion
easier.

Regards,

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

I've found numbered sections to be useful when modifying the
DocBook DTD
so that you can use it to create documents similar to those
created by
the commercial Information Mapping system.

In such a system, you build documents from the bottom up,
rather than
from the top down.

All text goes within the lowest level, say, a Sect3, and a
Chapter would
be made up of a group of Sect2 elements. I call this a
topic-point
structure, in which the Sect2 elements are the Topics within
the
chapter, and the Sect3 elements are the Points containing
the text.

If, as you develop the document, you find you have too many
Sect2
elements (Topics), you group them under new Sect1 elements.

It seems to me to be a natural way to write because the
structure
develops out of the material as you discover it.

And there's no problem with reuse because the lowest level
is always the
one containing the text.

If you wanted a somewhat deeper hierarchy, you could start
with a Sect4
(Point) at the bottom, and it would be possible to have a
Sect3 (Topic)
immediately under the Chapter. As you developed the book,
you could add
Sect2 and Sect1 levels as necessary.

Of course, all this requires some (rather small)
modifications to the
DocBook DTD.

Dave Nilsson


-----Original Message-----
From: Rock Lobster [mailto:emailchristian-gleinser.de] 
Sent: Friday, April 13, 2007 4:56 AM
To: docbooklists.oasis-open.org
Subject: [docbook] should I use section or sect1, sect2,
sect3 etc?


Hello,

I'm somehow confused on whether I should use nested
<section> tags, or
the "predefined" <sect1> to <sect5>.
Are there any benefits in using the latter? Are there any
reasons why
one way should be avoided in certain situations?

Thanks in advance!
--
View this message in context:
http://www.nabble.com/should-I-use-secti
on-or-sect1%2C-sect2%2C-sect3-et
c--tf3570509.html#a9975240
Sent from the docbook General mailing list archive at
Nabble.com.


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

 
Without doing any mods to the DTD you could use simplesect
as the text
holder (Point) and use section as the (Topic). One advantage
of this
break down is that simplesect enforces the structure by
disallowing any
further decomposition into smaller sections.

> -----Original Message-----
> From: Nilsson, David F [mailto:dfnilssonswitch.com] 
> Sent: Tuesday, April 17, 2007 10:43 AM
> To: Rock Lobster; docbooklists.oasis-open.org
> Subject: RE: [docbook] should I use section or sect1,
sect2, 
> sect3 etc?
> 
> I've found numbered sections to be useful when
modifying the 
> DocBook DTD so that you can use it to create documents

> similar to those created by the commercial Information
Mapping system.
> 
> In such a system, you build documents from the bottom
up, 
> rather than from the top down.
> 
> All text goes within the lowest level, say, a Sect3,
and a 
> Chapter would be made up of a group of Sect2 elements.
I call 
> this a topic-point structure, in which the Sect2
elements are 
> the Topics within the chapter, and the Sect3 elements
are the 
> Points containing the text.
> 
> If, as you develop the document, you find you have too
many 
> Sect2 elements (Topics), you group them under new Sect1
elements.
> 
> It seems to me to be a natural way to write because the

> structure develops out of the material as you discover
it.
> 
> And there's no problem with reuse because the lowest
level is 
> always the one containing the text.
> 
> If you wanted a somewhat deeper hierarchy, you could
start 
> with a Sect4
> (Point) at the bottom, and it would be possible to have
a 
> Sect3 (Topic) immediately under the Chapter. As you
developed 
> the book, you could add
> Sect2 and Sect1 levels as necessary.
> 
> Of course, all this requires some (rather small) 
> modifications to the DocBook DTD.
> 
> Dave Nilsson
> 
> 
> -----Original Message-----
> From: Rock Lobster [mailto:emailchristian-gleinser.de]
> Sent: Friday, April 13, 2007 4:56 AM
> To: docbooklists.oasis-open.org
> Subject: [docbook] should I use section or sect1,
sect2, sect3 etc?
> 
> 
> Hello,
> 
> I'm somehow confused on whether I should use nested
<section> tags, or
> the "predefined" <sect1> to
<sect5>.
> Are there any benefits in using the latter? Are there
any reasons why
> one way should be avoided in certain situations?
> 
> Thanks in advance!
> --
> View this message in context:
> http://www.nabble.com/should-I-use-section-or-sect
1%2C-sect2%2
C-sect3-et
> c--tf3570509.html#a9975240
> Sent from the docbook General mailing list archive at
Nabble.com.
> 
> 
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-helplists.oasis-open.org
> 
> 
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-helplists.oasis-open.org
> 
> 

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Eric,

Interesting approach. I particularly like the use of
simplesect as a
terminal section.

For us, we could use simplesect, but for the other sections
I think we
would need to stick to sect1, sect2, etc. 

We're using FrameMaker, and I don't think I can get Frame's
proprietary
stylesheet to apply styles (to the recursive
"section" elements) on the
basis of children. It applies heading styles chiefly on the
basis of
ancestors, often just by counting them. The count, of
course, can vary
in our bottom-up system.

This would not be a problem with XSLT.

Dave Nilsson 


-----Original Message-----
From: Johnson, Eric [mailto:Eric.Johnsoniona.com]

Sent: Tuesday, April 17, 2007 11:45 AM
To: docbooklists.oasis-open.org
Subject: RE: [docbook] should I use section or sect1, sect2,
sect3 etc?

 
Without doing any mods to the DTD you could use simplesect
as the text
holder (Point) and use section as the (Topic). One advantage
of this
break down is that simplesect enforces the structure by
disallowing any
further decomposition into smaller sections.

> -----Original Message-----
> From: Nilsson, David F [mailto:dfnilssonswitch.com]
> Sent: Tuesday, April 17, 2007 10:43 AM
> To: Rock Lobster; docbooklists.oasis-open.org
> Subject: RE: [docbook] should I use section or sect1,
sect2,
> sect3 etc?
> 
> I've found numbered sections to be useful when
modifying the DocBook 
> DTD so that you can use it to create documents similar
to those 
> created by the commercial Information Mapping system.
> 
> In such a system, you build documents from the bottom
up, rather than 
> from the top down.
> 
> All text goes within the lowest level, say, a Sect3,
and a Chapter 
> would be made up of a group of Sect2 elements. I call
this a 
> topic-point structure, in which the Sect2 elements are
the Topics 
> within the chapter, and the Sect3 elements are the
Points containing 
> the text.
> 
> If, as you develop the document, you find you have too
many
> Sect2 elements (Topics), you group them under new Sect1
elements.
> 
> It seems to me to be a natural way to write because the
structure 
> develops out of the material as you discover it.
> 
> And there's no problem with reuse because the lowest
level is always 
> the one containing the text.
> 
> If you wanted a somewhat deeper hierarchy, you could
start with a 
> Sect4
> (Point) at the bottom, and it would be possible to have
a
> Sect3 (Topic) immediately under the Chapter. As you
developed the 
> book, you could add
> Sect2 and Sect1 levels as necessary.
> 
> Of course, all this requires some (rather small)
modifications to the 
> DocBook DTD.
> 
> Dave Nilsson
> 
> 
> -----Original Message-----
> From: Rock Lobster [mailto:emailchristian-gleinser.de]
> Sent: Friday, April 13, 2007 4:56 AM
> To: docbooklists.oasis-open.org
> Subject: [docbook] should I use section or sect1,
sect2, sect3 etc?
> 
> 
> Hello,
> 
> I'm somehow confused on whether I should use nested
<section> tags, or

> the "predefined" <sect1> to
<sect5>.
> Are there any benefits in using the latter? Are there
any reasons why 
> one way should be avoided in certain situations?
> 
> Thanks in advance!
> --
> View this message in context:
> http://www.nabble.com/should-I-use-section-or-sect
1%2C-sect2%2
C-sect3-et
> c--tf3570509.html#a9975240
> Sent from the docbook General mailing list archive at
Nabble.com.
> 
> 
------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org