Bug 616123

Summary:	RFE: expose DocBook bridgehead.in.toc option
Product:	[Community] Publican	Reporter:	Douglas Silas <dhensley>
Component:	publican	Assignee:	Jeff Fearn 🐞 <jfearn>
Status:	CLOSED ERRATA	QA Contact:	Fedora Extras Quality Assurance <extras-qa>
Severity:	medium	Docs Contact:
Priority:	low
Version:	1.6	CC:	jfearn, mmcallis, publican-list, rlandman
Target Milestone:	---
Target Release:	---
Hardware:	All
OS:	Linux
Whiteboard:
Fixed In Version:	publican-2.2-0.fc13	Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2010-10-08 20:43:43 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Douglas Silas 2010-07-19 17:41:03 UTC

Description of problem: Two settings controlling TOC creation are:

generate_section_toc_level: 0
# controls the section depth at which Publican will generate a table of contents. At the default value of 0, Publican will generate tables of contents at the start of the document and in parts, chapters, and appendixes, but not in sections. If (for example) the value is set to 1, tables of contents also appear in each "level 1" section, such as sections 1.1, 1.2, 2.1, and 2.2. If set to 2, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.

toc_section_depth: 2
# controls the depth of sections that Publican includes in the main table of contents. By default, this value is set to 2. With the default setting, sections 1.1 and 1.1.1 will appear in the main table of contents, but section 1.1.1.1 will not. (Note that the first digit in these examples represents a chapter, not a section).

Note that the combination of these does not, for example, allow for setting the main TOC to have a level of 1, while chapters/sections have a level of 2. It would be both logical and useful for a (large, long) book's TOC to have a shallow section depth (, while the chapter or section's TOC is more detailed.

My proposal is to have separate "main_toc_section_depth" and "division_toc_section_depth" directives that control the initial and all later TOC section depths, respectively, thus allowing for more fine-grained control over navigation, appearance and organization.

Note: the description for toc_section_depth reads "controls the depth of sections that Publican includes in the main table of contents". Is there a (hidden) option to control the TOC depth of other divisions, or does this need to be revised? toc_section_depth affects all TOCs.

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

Comment 1 Jeff Fearn 🐞 2010-07-27 06:26:02 UTC

Publican doesn't control how these things works, it just exposes some of the _many_ configuration options DocBook has.

It's possible this already works in DocBook but isn't exposed by Publican.

Dues to limitations in how the config files work we have to replace dots in the DocBook parameters with underscores, so generate_section_toc_level is in reality the DocBook parameter generate.section.toc.level

There are other TOC parameters in DocBook, we can expose the ones you need.

You might want to take a look at generate.section.toc.level and toc.max.depth at http://docbook.sourceforge.net/release/xsl/current/doc/html/toc_index.html

If these aren't enough then you will need to open a discussion with the DocBook team about modifying their style sheets.

If they are what you need then we can expose the ones you need via the config file.

Comment 2 Douglas Silas 2010-08-03 07:37:47 UTC

Thanks Jeff. I will take a look at the other DocBook parameters soon, and reply.

Cheers,

Silas

Comment 3 Douglas Silas 2010-08-17 11:54:07 UTC

Jeff,

I don't think any (combination) of the exposable options would allow us to have a main TOC level of 1, and a chapter TOC level of 2. generate.section.toc.level only controls where a TOC is generated, not the actual level in those generated TOCs (and sub-TOCs). toc.max.depth seems to only control the maximum depth level for all TOCs. It seems equivalent to toc_section_depth (but I wonder why). toc_section_depth controls the maximum level for all TOCs (main and in sections). 

However, I am very interested in this parameter: bridgehead.in.toc

I sometimes use bridgeheads instead of creating 4th level sections (for example: 11.4.2.1. Site Configuration), and I think having unnumbered bridgehead entries in the TOCs would be very useful. 4th-level section numbers are hideous and only rarely necessary, while bridgehead entries would look much nicer. Could you expose this option?

Thanks,

Silas

Comment 4 Ruediger Landmann 2010-10-04 01:09:34 UTC

DocBook doesn't allow us to control main and division TOC levels independently; this would be a feature request in DocBook itself:

http://sourceforge.net/tracker/?group_id=21935&atid=384107

However, we could take a look at exposing bridgehead.in.toc, so I'm updating the summary to reflect this.

Comment 5 Jeff Fearn 🐞 2010-10-04 02:35:01 UTC

Added bridgehead_in_toc parameter to publican.cfg, defaults to 0.

Fixed in build: 2.1-%{?dist}.t141

Comment 6 Douglas Silas 2010-10-04 18:08:38 UTC

Thanks!

Comment 7 Fedora Update System 2010-10-06 05:50:07 UTC

publican-2.2-0.fc13 has been submitted as an update for Fedora 13.
https://admin.fedoraproject.org/updates/publican-2.2-0.fc13

Comment 8 Fedora Update System 2010-10-06 05:51:22 UTC

publican-2.2-0.fc12 has been submitted as an update for Fedora 12.
https://admin.fedoraproject.org/updates/publican-2.2-0.fc12

Comment 9 Fedora Update System 2010-10-06 05:51:22 UTC

publican-2.2-0.fc14 has been submitted as an update for Fedora 14.
https://admin.fedoraproject.org/updates/publican-2.2-0.fc14

Comment 10 Fedora Update System 2010-10-08 20:41:32 UTC

publican-2.2-0.fc13 has been pushed to the Fedora 13 stable repository.  If problems still persist, please make note of it in this bug report.