Bug 482784 - RFE: Support refentry
RFE: Support refentry
Product: Publican
Classification: Community
Component: publican (Show other bugs)
All Linux
low Severity medium
: ---
: ---
Assigned To: Ruediger Landmann
Joshua Wulf
: Documentation
Depends On:
  Show dependency treegraph
Reported: 2009-01-27 22:55 EST by Don Domingo
Modified: 2014-10-19 18:56 EDT (History)
7 users (show)

See Also:
Fixed In Version: 1.0
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2009-11-25 23:59:08 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)
how old structure is displayed (64.03 KB, image/png)
2009-01-28 21:14 EST, Jeff Fearn
no flags Details
looking good (57.94 KB, image/png)
2009-01-28 21:14 EST, Jeff Fearn
no flags Details

  None (edit)
Description Don Domingo 2009-01-27 22:55:58 EST
Description of problem:
 the presentation of <refentry> and all valid nested tags could be improved through the following:

** instead of using "Name" as a primary header, use the string tagged <refentrytitle><phrase>blah</phrase></refentrytitle> (at least in html, html-single, and pdf)

** "Synopsis" header is bigger than "Name" in html and html-single

** in pdf, each page only contains one <refentry>. perhaps we could fit as many <refentry> entries in a page as possible? 

** indent <refsynopsisdiv>, <refsect1>, and other sections nested in <refentry> to emphasize "ownership" and division between reference entries.

Version-Release number of selected component (if applicable):


How reproducible:
the following source book is composed entirely of <refentry> entries:

Steps to Reproduce:
1. Check out SVN repo:

2. run make pdf-en-US html-en-US html-single-en-US.

3. inspect final builds.
Actual results:

** "Name" is used as the main header for each reference entry in the final build
** in html and html-single, font for "Synopsis" header is larger than all other headers, even though it's a nested header
** in PDF, it's one page per reference entry.
** in all builds, nested headers and sections are not indented.

Desired results:

** Instead of "Name", use the string tagged  <refentrytitle><phrase>blah</phrase></refentrytitle> as the main header.

** shrink the "Synopsis" font to be the same size as all the others

** in PDF, fit as much <refentry> content as possible in a page 

** in all builds, indent nested headers and content to emphasize nesting (the same way we indent all nested content in a <varlistentry>).

Additional info:
Comment 1 Jared Smith 2009-01-28 08:41:52 EST
In the case of the "single refentry per page" problem, can't you simply add 

<xsl:param name="refentry.pagebreak">0</xsl:param>

to the XSL customization layer?  That should do the trick.
Comment 2 Jeff Fearn 2009-01-28 18:52:33 EST
None of these tags are actually supported tags ATM; these tags are using default settings and we need to look in to what is supportable use in the long term.

On my initial inspection of the XML it looks to me that using better tag selection may help.

The section titled "A typical reference page for a function:" at http://www.docbook.org/tdg/en/html/refentry.html has a much better structure for function specification that what is currently being used.

I tested the XML from the above link and although it was not perfect, it was considerable better laid out that the current approach.

I also recommend switching from refsect1 to refsection. Using refsect1 forces it to be marked up as a level 1 section, this will prevent depth based styling.
Comment 3 Jeff Fearn 2009-01-28 21:14:17 EST
Created attachment 330307 [details]
how old structure is displayed
Comment 4 Jeff Fearn 2009-01-28 21:14:59 EST
Created attachment 330308 [details]
looking good
Comment 5 Jeff Fearn 2009-01-28 21:18:21 EST
This new image represents how switching to the XML structure I mentioned above looks when using ANSI styled function definitions.

The default function definition style is K&R, which is ugly and makes babies cry.
Comment 6 Brian Forte 2009-01-28 21:25:22 EST
I checked in an edited Tapset_Reference_Guide.xml containing three examples of the structure as noted above by jfearn.

The first example uses printf, the second two are edits of two extant entries (cpu and euid).

NB: the 'looking good' screenshot above is consequent to a publican change that, as of this typing, hasn't gone public.
Comment 7 Michael Hideo 2009-06-16 21:58:28 EDT
Don can you test this with the latest version of publican that you are using? - Mike
Comment 8 Jeff Fearn 2009-08-10 19:24:32 EDT
This should be fixed in the BETA.
Comment 9 Ruediger Landmann 2009-09-08 01:12:20 EDT
Seems to be fixed in 0.44, but not in 1.0.

I tested this with [1], as in the original report. I had to comment out the following line in Tapset_Reference_Guide.xml to get it to build:

<xi:include href="refentry-example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

However, without that line, the book built fine in 0.44 and gave me the output illustrated in the "looking good" attachment here. 

In 1.0, I get this error multiple times:

runtime error: file /usr/share/Publican/xsl/xhtml-common.xsl line 967 element attribute
xsl:attribute: Cannot add attributes to an element if children have been already added to the element.

and the book doesn't build.

Comment 10 Jeff Fearn 2009-09-08 19:31:13 EDT
Working of the latest upstream test version the following change set works as expected; so I can't duplicate the error :(

Note I moved the offending xi:include below the para's to bypass the error.

$ svn diff -x -u
Index: en-US/Tapset_Reference_Guide.ent
--- en-US/Tapset_Reference_Guide.ent	(revision 21821)
+++ en-US/Tapset_Reference_Guide.ent	(working copy)
@@ -2,4 +2,6 @@
 <!ENTITY BOOKID "Tapset_Reference_Guide">
 <!ENTITY YEAR "2008">
 <!ENTITY RHEL "Red Hat Enterprise Linux 5">
-<!ENTITY APH "'">
\ No newline at end of file
+<!ENTITY APH "'">
+<!ENTITY HOLDER "Red Hat, Inc">
Index: en-US/Tapset_Reference_Guide.xml
--- en-US/Tapset_Reference_Guide.xml	(revision 21821)
+++ en-US/Tapset_Reference_Guide.xml	(working copy)
@@ -28,10 +28,6 @@
 <section id="format">
 <title>Tapset Name Format</title>
-<para>In this guide, tapset definitions appear in the following format:</para>
-<xi:include href="refentry-example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 The <replaceable>return</replaceable> field specifies what data type the
 tapset extracts and returns from the kernel during a probe (and thus,
@@ -48,6 +44,10 @@
 exit functions, and print functions.
+<para>In this guide, tapset definitions appear in the following format:</para>
+<xi:include href="refentry-example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Comment 11 Ruediger Landmann 2009-09-09 02:58:46 EDT
Fixed in 1.0

OK -- whatever the problem is with my build, it's not with Publican.

I copied one of the Refentries into a fresh book and tested it there within a section and within a chapter and it worked fine, giving the same output
illustrated in the "looking good" attachment.
Comment 13 Fedora Update System 2009-11-17 21:19:23 EST
publican-1.2-0.fc12 has been submitted as an update for Fedora 12.
Comment 14 Fedora Update System 2009-11-20 00:18:32 EST
publican-1.2-0.fc12 has been pushed to the Fedora 12 stable repository.  If problems still persist, please make note of it in this bug report.
Comment 15 Fedora Update System 2009-11-25 09:53:39 EST
publican-1.2-0.fc11 has been pushed to the Fedora 11 stable repository.  If problems still persist, please make note of it in this bug report.

Note You need to log in before you can comment on or make changes to this bug.