refentry or section

Hi All,

I'm documenting some software apis, and was thinking of
using sections
(rather than sect1,2, etc due to possible reuse). Have since
sound
references and refentries.

Is the main advantage of using references and refentries
that you can
format them in a different manner to sections containing
other text?
Is that a strong enough reason to use them? What do you all
use for
apis in docbook?

Thanks in advance for any thoughts

S

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

I think you're dealing with apples and oranges.

A reference is (I think) designed to be used for reference
information, 
often presented in a dictionary-style for easy lookup. A
reference is a 
collection of refentries, similar to a book comprising a
bunch of 
chapters or articles. In addition to the normal kinds of
output like 
HTML and PDF, refentries can also be transformed by the
standard docbook 
xsl stylesheets to create man pages.

By contrast, sections are general-purpose modules that might
contain any 
kind of information (not just reference info). And they are
usually 
smaller in scope - for example an article or chapter might
be made up of 
sections. The analog of a section in a referentry is a
refentry.

For more (and better) info, see Norm Walsh's  book, 
http:
//www.docbook.org/tdg/en/html/docbook.html - esp. the
chapter on 
Creating Docbook Documents.



Samuel Wright wrote:
> Hi All,
> 
> I'm documenting some software apis, and was thinking of
using sections
> (rather than sect1,2, etc due to possible reuse). Have
since sound
> references and refentries.
> 
> Is the main advantage of using references and
refentries that you can
> format them in a different manner to sections
containing other text?
> Is that a strong enough reason to use them? What do you
all use for
> apis in docbook?
> 
> Thanks in advance for any thoughts
> 
> S
> 
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-apps-helplists.oasis-open.org
> 
> 


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

Sorry, I meant to say, the analog of a section is a
refsection.

Also, I think a reference can be a good choice for an API,
for the 
reason that you guessed: it's designed to give you a regular
structure 
that makes information easy to up. I think that's what most
people do 
with API docs. Non-reference components (chapters,
articles), are less 
restrictive, more suitable (I would argue) for more
narrative or 
variable content.




Samuel Wright wrote:
> Hi All,
> 
> I'm documenting some software apis, and was thinking of
using sections
> (rather than sect1,2, etc due to possible reuse). Have
since sound
> references and refentries.
> 
> Is the main advantage of using references and
refentries that you can
> format them in a different manner to sections
containing other text?
> Is that a strong enough reason to use them? What do you
all use for
> apis in docbook?
> 
> Thanks in advance for any thoughts
> 
> S
> 
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-apps-helplists.oasis-open.org
> 
> 


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

Dennis,
Cheers for the answer.

On 30/05/07, Denis Bradford <denis.bradfordverizon.net> wrote:
> A reference is (I think) designed to be used for
reference information,
> often presented in a dictionary-style for easy lookup.
A reference is a
> collection of refentries, similar to a book comprising
a bunch of
> chapters or articles. In addition to the normal kinds
of output like
> HTML and PDF, refentries can also be transformed by the
standard docbook
> xsl stylesheets to create man pages.

Exactly. Man pages do not interest me at this point. I am
aware the
reference pages were originally create to enable man page
output. What
I am interested in knowing is despite not needing man pages,
is there
any advantage in using refentries to hold my api information
than
sections and subsections.

The only clear advantage I see is that you have a different
container
for "dictionary style" information, and thus can
format that
differently to your textual sections. The actual markup  of
a refentry
does not seem to add anything beyond what I can put in a
section,
using funcsynopsis and sects or simplesects for synopsis,
description,
etc...

Using sections rather than sect1 and sect2 means I can reuse
them at a
different levels in the documentation, which I think is
slightly more
difficult with refentries, as they can embedded within
chapters and
parts but not sections.

"The value of a separate hierarchical structure is that
it allows the
content model of sections in reference pages to be
customized
differently than the content model of sections outside. For
example,
because of this split, it was easy to add a recursive
sectioning
element (Section) as a peer to Sect1 in DocBook V3.1
without
introducing it to RefEntrys, in which it would not be
desirable."[1]

Is not very clear at all.

> By contrast, sections are general-purpose modules that
might contain any
> kind of information (not just reference info). And they
are usually
> smaller in scope - for example an article or chapter
might be made up of
> sections. The analog of a section in a referentry is a
refentry.

Granted sections are more general, but the scope is pretty
much what
you make it. As far as I see it you could skip chapters
entirely, and
just use sections. And as you can have sections within
sections, you
can use them as refsection or refentry.

> For more (and better) info, see Norm Walsh's  book,
> http:
//www.docbook.org/tdg/en/html/docbook.html - esp. the
chapter on
> Creating Docbook Documents.

Yes, I have read that.

> Also, I think a reference can be a good choice for an
API, for the
> reason that you guessed: it's designed to give you a
regular structure
> that makes information easy to up. I think that's what
most people do
> with API docs. Non-reference components (chapters,
articles), are less
> restrictive, more suitable (I would argue) for more
narrative or
> variable content.

So to sum up here, I feel as though I _should_ use
references,
refsections and refentries for my api information, and
chapters/sections/etc for my other content, _BUT_ I don't
see that
much advantage in doing so, and you also accrue some extra
markup for
no great reason.

Any more thoughts?

Thanks
S

[1] http
://www.docbook.org/tdg/en/html/refsect1.html

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

Not sure it justifies the extra markup, but in terms of what
the xsls
do, one thing you get with a reference and refentries that
you don't
with a chapter and sections is additional summary info (the
refpurpose)
in the toc. You can see this in the toc for tdg under
"I. DocBook
Element Reference" where the toc has the element name
and the refpurpose
instead of just the section's title:
http:
//www.docbook.org/tdg/en/html/docbook.html

On the other hand, the <reference> has to be the child
of a book (i.e.
it's like a <chapter>). I've found myself wanting to
use a <reference>
as if it were a <section>.

David

> 
> So to sum up here, I feel as though I _should_ use 
> references, refsections and refentries for my api 
> information, and chapters/sections/etc for my other
content, 
> _BUT_ I don't see that much advantage in doing so, and
you 
> also accrue some extra markup for no great reason.
> 
> Any more thoughts?

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

Has anyone figured out how to include the title of the
refentry in a
running header? For section headings, I retrieve the
section.head.marker
using the following:

<fo:retrieve-marker
retrieve-class-name="section.head.marker"
retrieve-position="first-including-carryover"
retrieve-boundary="page-sequence"/>

However, no marker is retrieved for refentry pages, and on
those pages
the header is blank.

Regards,
Jeff Powanda
 

-----Original Message-----
From: David Cramer (Tech Pubs) [mailto:dcramermotive.com] 
Sent: Wednesday, May 30, 2007 7:57 AM
To: Samuel Wright; denis.bradfordverizon.net;
docbook-appslists.oasis-open.org
Subject: RE: [docbook-apps] refentry or section

Not sure it justifies the extra markup, but in terms of what
the xsls
do, one thing you get with a reference and refentries that
you don't
with a chapter and sections is additional summary info (the
refpurpose)
in the toc. You can see this in the toc for tdg under
"I. DocBook
Element Reference" where the toc has the element name
and the refpurpose
instead of just the section's title:
http:
//www.docbook.org/tdg/en/html/docbook.html

On the other hand, the <reference> has to be the child
of a book (i.e.
it's like a <chapter>). I've found myself wanting to
use a <reference>
as if it were a <section>.

David

> 
> So to sum up here, I feel as though I _should_ use 
> references, refsections and refentries for my api 
> information, and chapters/sections/etc for my other
content, 
> _BUT_ I don't see that much advantage in doing so, and
you 
> also accrue some extra markup for no great reason.
> 
> Any more thoughts?

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


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

Ah, finally figured this out. I customized the refnamediv
template and
made sure it created markers for level 1 and level 2:

      <xsl:when test="$section.level = 1">
        <fo:block
xsl:use-attribute-sets="refentry.title.properties"
>
          <fo:marker
marker-class-name="section.head.marker">
          	<xsl:value-of
select="$reftitle"/>
          </fo:marker>
          <fo:block
xsl:use-attribute-sets="section.title.level1.properties
">
            <xsl:value-of
select="$reftitle"/>
          </fo:block>
        </fo:block>
      </xsl:when>
      <xsl:when test="$section.level = 2">
        <fo:block
xsl:use-attribute-sets="refentry.title.properties"
>
          <fo:marker
marker-class-name="section.head.marker">
          	<xsl:value-of
select="$reftitle"/>
          </fo:marker>
          <fo:block
xsl:use-attribute-sets="section.title.level2.properties
">
            <xsl:value-of
select="$reftitle"/>
          </fo:block>
        </fo:block>
      </xsl:when>

Now I've got running headers for refentry titles.

Regards,
Jeff Powanda
 

-----Original Message-----
From: Jeff Powanda 
Sent: Wednesday, May 30, 2007 6:19 PM
To: 'David Cramer (Tech Pubs)'; Samuel Wright;
denis.bradfordverizon.net; docbook-appslists.oasis-open.org
Subject: RE: [docbook-apps] refentry or section


Has anyone figured out how to include the title of the
refentry in a
running header? For section headings, I retrieve the
section.head.marker
using the following:

<fo:retrieve-marker
retrieve-class-name="section.head.marker"
retrieve-position="first-including-carryover"
retrieve-boundary="page-sequence"/>

However, no marker is retrieved for refentry pages, and on
those pages
the header is blank.

Regards,
Jeff Powanda
 

-----Original Message-----
From: David Cramer (Tech Pubs) [mailto:dcramermotive.com] 
Sent: Wednesday, May 30, 2007 7:57 AM
To: Samuel Wright; denis.bradfordverizon.net;
docbook-appslists.oasis-open.org
Subject: RE: [docbook-apps] refentry or section

Not sure it justifies the extra markup, but in terms of what
the xsls
do, one thing you get with a reference and refentries that
you don't
with a chapter and sections is additional summary info (the
refpurpose)
in the toc. You can see this in the toc for tdg under
"I. DocBook
Element Reference" where the toc has the element name
and the refpurpose
instead of just the section's title:
http:
//www.docbook.org/tdg/en/html/docbook.html

On the other hand, the <reference> has to be the child
of a book (i.e.
it's like a <chapter>). I've found myself wanting to
use a <reference>
as if it were a <section>.

David

> 
> So to sum up here, I feel as though I _should_ use 
> references, refsections and refentries for my api 
> information, and chapters/sections/etc for my other
content, 
> _BUT_ I don't see that much advantage in doing so, and
you 
> also accrue some extra markup for no great reason.
> 
> Any more thoughts?

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


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

Hi Jeff

I gladly found your posting to produce a running header of
refentries. But
unfortunately, it is not working correctly for my
customization layer, since
I'm using double side printing. What I get is on even pages
the correct
refname, but on odd pages the name from the previous
refentry starting on an
odd page. And vice versa if the refentry is starting on an
odd page.

It seems to me, that there are two variables, one for even
and one for odd
pages, and both of them have to be set.

I'm retrieving the marker in the running header in the
following way:

					<fo:retrieve-marker
						retrieve-class-name="section.head.marker"
						retrieve-position="first-including-carryover"
;
						retrieve-boundary="page-sequence" />

Do you have an idea how this could be fixed? 

I'm using Docbook: 1.73 and FOP: 0.93

Thanks and best regards

Daniel


Jeff Powanda wrote:
> 
> Ah, finally figured this out. I customized the
refnamediv template and
> made sure it created markers for level 1 and level 2:
> 
>       <xsl:when test="$section.level =
1">
>         <fo:block
xsl:use-attribute-sets="refentry.title.properties"
>
>           <fo:marker
marker-class-name="section.head.marker">
>           	<xsl:value-of
select="$reftitle"/>
>           </fo:marker>
>           <fo:block
>
xsl:use-attribute-sets="section.title.level1.properties
">
>             <xsl:value-of
select="$reftitle"/>
>           </fo:block>
>         </fo:block>
>       </xsl:when>
>       <xsl:when test="$section.level =
2">
>         <fo:block
xsl:use-attribute-sets="refentry.title.properties"
>
>           <fo:marker
marker-class-name="section.head.marker">
>           	<xsl:value-of
select="$reftitle"/>
>           </fo:marker>
>           <fo:block
>
xsl:use-attribute-sets="section.title.level2.properties
">
>             <xsl:value-of
select="$reftitle"/>
>           </fo:block>
>         </fo:block>
>       </xsl:when>
> 
> Now I've got running headers for refentry titles.
> 
> Regards,
> Jeff Powanda
>  
> 
> -----Original Message-----
> From: Jeff Powanda 
> Sent: Wednesday, May 30, 2007 6:19 PM
> To: 'David Cramer (Tech Pubs)'; Samuel Wright;
> denis.bradfordverizon.net; docbook-appslists.oasis-open.org
> Subject: RE: [docbook-apps] refentry or section
> 
> 
> Has anyone figured out how to include the title of the
refentry in a
> running header? For section headings, I retrieve the
section.head.marker
> using the following:
> 
> <fo:retrieve-marker
retrieve-class-name="section.head.marker"
>
retrieve-position="first-including-carryover"
> retrieve-boundary="page-sequence"/>
> 
> However, no marker is retrieved for refentry pages, and
on those pages
> the header is blank.
> 
> Regards,
> Jeff Powanda
>  
> 
> -----Original Message-----
> From: David Cramer (Tech Pubs) [mailto:dcramermotive.com] 
> Sent: Wednesday, May 30, 2007 7:57 AM
> To: Samuel Wright; denis.bradfordverizon.net;
> docbook-appslists.oasis-open.org
> Subject: RE: [docbook-apps] refentry or section
> 
> Not sure it justifies the extra markup, but in terms of
what the xsls
> do, one thing you get with a reference and refentries
that you don't
> with a chapter and sections is additional summary info
(the refpurpose)
> in the toc. You can see this in the toc for tdg under
"I. DocBook
> Element Reference" where the toc has the element
name and the refpurpose
> instead of just the section's title:
> http:
//www.docbook.org/tdg/en/html/docbook.html
> 
> On the other hand, the <reference> has to be the
child of a book (i.e.
> it's like a <chapter>). I've found myself wanting
to use a <reference>
> as if it were a <section>.
> 
> David
> 
>> 
>> So to sum up here, I feel as though I _should_ use

>> references, refsections and refentries for my api 
>> information, and chapters/sections/etc for my other
content, 
>> _BUT_ I don't see that much advantage in doing so,
and you 
>> also accrue some extra markup for no great reason.
>> 
>> Any more thoughts?
> 
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-apps-helplists.oasis-open.org
> 
> 
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-apps-helplists.oasis-open.org
> 
> 
> 

-- 
View this message in context: http://www.nabble.com/refentry-or-section-tf38
35079.html#a12296662
Sent from the docbook apps mailing list archive at
Nabble.com.


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

I solved the problem adding the marker as well to the
refsect1 template.


<xsl:template match="refsect1">
		<xsl:variable name="id">
			<xsl:call-template name="object.id" />
		</xsl:variable>

<xsl:variable name="reftitle">
	<xsl:choose>
		<xsl:when
test="../refmeta/refentrytitle">
			<xsl:apply-templates
				select="../refmeta/refentrytitle" />
		</xsl:when>
		<xsl:otherwise>

		</xsl:otherwise>
	</xsl:choose>
</xsl:variable>

		<fo:block id="{$id}">
<fo:marker
marker-class-name="section.head.marker">
		<xsl:value-of select="$reftitle" />
</fo:marker>
			<xsl:call-template name="refsect1.titlepage"
/>
			<xsl:apply-templates />
		</fo:block>
		
	</xsl:template>



Dan Stainhauser wrote:
> 
> Hi Jeff
> 
> I gladly found your posting to produce a running header
of refentries. But
> unfortunately, it is not working correctly for my
customization layer,
> since I'm using double side printing. What I get is on
even pages the
> correct refname, but on odd pages the name from the
previous refentry
> starting on an odd page. And vice versa if the refentry
is starting on an
> odd page.
> 
> It seems to me, that there are two variables, one for
even and one for odd
> pages, and both of them have to be set.
> 
> I'm retrieving the marker in the running header in the
following way:
> 
> 					<fo:retrieve-marker
>
						retrieve-class-name="section.head.marker"
>
						retrieve-position="first-including-carryover"
;
> 						retrieve-boundary="page-sequence"
/>
> 
> Do you have an idea how this could be fixed? 
> 
> I'm using Docbook: 1.73 and FOP: 0.93
> 
> Thanks and best regards
> 
> Daniel
> 
> 
> Jeff Powanda wrote:
>> 
>> Ah, finally figured this out. I customized the
refnamediv template and
>> made sure it created markers for level 1 and level
2:
>> 
>>       <xsl:when test="$section.level =
1">
>>         <fo:block
xsl:use-attribute-sets="refentry.title.properties"
>
>>           <fo:marker
marker-class-name="section.head.marker">
>>           	<xsl:value-of
select="$reftitle"/>
>>           </fo:marker>
>>           <fo:block
>>
xsl:use-attribute-sets="section.title.level1.properties
">
>>             <xsl:value-of
select="$reftitle"/>
>>           </fo:block>
>>         </fo:block>
>>       </xsl:when>
>>       <xsl:when test="$section.level =
2">
>>         <fo:block
xsl:use-attribute-sets="refentry.title.properties"
>
>>           <fo:marker
marker-class-name="section.head.marker">
>>           	<xsl:value-of
select="$reftitle"/>
>>           </fo:marker>
>>           <fo:block
>>
xsl:use-attribute-sets="section.title.level2.properties
">
>>             <xsl:value-of
select="$reftitle"/>
>>           </fo:block>
>>         </fo:block>
>>       </xsl:when>
>> 
>> Now I've got running headers for refentry titles.
>> 
>> Regards,
>> Jeff Powanda
>>  
>> 
>> -----Original Message-----
>> From: Jeff Powanda 
>> Sent: Wednesday, May 30, 2007 6:19 PM
>> To: 'David Cramer (Tech Pubs)'; Samuel Wright;
>> denis.bradfordverizon.net; docbook-appslists.oasis-open.org
>> Subject: RE: [docbook-apps] refentry or section
>> 
>> 
>> Has anyone figured out how to include the title of
the refentry in a
>> running header? For section headings, I retrieve
the section.head.marker
>> using the following:
>> 
>> <fo:retrieve-marker
retrieve-class-name="section.head.marker"
>>
retrieve-position="first-including-carryover"
>> retrieve-boundary="page-sequence"/>
>> 
>> However, no marker is retrieved for refentry pages,
and on those pages
>> the header is blank.
>> 
>> Regards,
>> Jeff Powanda
>>  
>> 
>> -----Original Message-----
>> From: David Cramer (Tech Pubs) [mailto:dcramermotive.com] 
>> Sent: Wednesday, May 30, 2007 7:57 AM
>> To: Samuel Wright; denis.bradfordverizon.net;
>> docbook-appslists.oasis-open.org
>> Subject: RE: [docbook-apps] refentry or section
>> 
>> Not sure it justifies the extra markup, but in
terms of what the xsls
>> do, one thing you get with a reference and
refentries that you don't
>> with a chapter and sections is additional summary
info (the refpurpose)
>> in the toc. You can see this in the toc for tdg
under "I. DocBook
>> Element Reference" where the toc has the
element name and the refpurpose
>> instead of just the section's title:
>> http:
//www.docbook.org/tdg/en/html/docbook.html
>> 
>> On the other hand, the <reference> has to be
the child of a book (i.e.
>> it's like a <chapter>). I've found myself
wanting to use a <reference>
>> as if it were a <section>.
>> 
>> David
>> 
>>> 
>>> So to sum up here, I feel as though I _should_
use 
>>> references, refsections and refentries for my
api 
>>> information, and chapters/sections/etc for my
other content, 
>>> _BUT_ I don't see that much advantage in doing
so, and you 
>>> also accrue some extra markup for no great
reason.
>>> 
>>> Any more thoughts?
>> 
>>
------------------------------------------------------------
---------
>> To unsubscribe, e-mail:
docbook-apps-unsubscribelists.oasis-open.org
>> For additional commands, e-mail:
docbook-apps-helplists.oasis-open.org
>> 
>> 
>>
------------------------------------------------------------
---------
>> To unsubscribe, e-mail:
docbook-apps-unsubscribelists.oasis-open.org
>> For additional commands, e-mail:
docbook-apps-helplists.oasis-open.org
>> 
>> 
>> 
> 
> 

-- 
View this message in context: http://www.nabble.com/refentry-or-section-tf38
35079.html#a12338304
Sent from the docbook apps mailing list archive at
Nabble.com.


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