|
»
refentry or section
|
View:
New views
9 Messages
—
Rating Filter:
Alert me
|
 |
refentry or section
by Samuel Wright
::
Rate this Message:
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-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
Re: refentry or section
by Denis Bradford
::
Rate this Message:
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-unsubscribe@... > For additional commands, e-mail: docbook-apps-help@... > > --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
Re: refentry or section
by Denis Bradford
::
Rate this Message:
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-unsubscribe@... > For additional commands, e-mail: docbook-apps-help@... > > --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
Re: refentry or section
by Samuel Wright
::
Rate this Message:
Dennis,
Cheers for the answer. On 30/05/07, Denis Bradford <denis.bradford@...> 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-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
RE: refentry or section
by David Cramer (Tech Pubs)
::
Rate this Message:
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-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
RE: refentry or section
by Jeff Powanda
::
Rate this Message:
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:dcramer@...] Sent: Wednesday, May 30, 2007 7:57 AM To: Samuel Wright; denis.bradford@...; docbook-apps@... 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-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
RE: refentry or section
by Jeff Powanda
::
Rate this Message:
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.bradford@...; docbook-apps@... 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:dcramer@...] Sent: Wednesday, May 30, 2007 7:57 AM To: Samuel Wright; denis.bradford@...; docbook-apps@... 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-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-apps-unsubscribe@... For additional commands, e-mail: docbook-apps-help@... |
|
|
RE: refentry or section
by Dan Stainhauser
::
Rate this Message:
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
|
|
|
RE: refentry or section
by Dan Stainhauser
::
Rate this Message:
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>
|
| Free embeddable forum powered by Nabble | Forum Help |
