Red Hat Bugzilla – Bug 482784
RFE: Support refentry
Last modified: 2014-10-19 18:56:45 EDT
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):
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.
** "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.
** 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>).
In the case of the "single refentry per page" problem, can't you simply add
to the XSL customization layer? That should do the trick.
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.
Created attachment 330307 [details]
how old structure is displayed
Created attachment 330308 [details]
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.
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.
Don can you test this with the latest version of publican that you are using? - Mike
This should be fixed in the BETA.
Seems to be fixed in 0.44, but not in 1.0.
I tested this with , 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.
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
--- 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">
--- en-US/Tapset_Reference_Guide.xml (revision 21821)
+++ en-US/Tapset_Reference_Guide.xml (working copy)
@@ -28,10 +28,6 @@
<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" />
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.
publican-1.2-0.fc12 has been submitted as an update for Fedora 12.
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.
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.