Bug 616142

Summary: RFC: building only part of a book by altering xrefs
Product: [Community] Publican Reporter: Douglas Silas <dhensley>
Component: publicanAssignee: Jeff Fearn 🐞 <jfearn>
Status: CLOSED ERRATA QA Contact: Fedora Extras Quality Assurance <extras-qa>
Severity: medium Docs Contact:
Priority: low    
Version: 1.6CC: dmison, 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:42:40 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 18:11:38 UTC
I have a request for consideration for a controversial feature that has two important and related use cases:

* I have a very large book to publish, but due to (various) reasons, only want to publish part of it. The content is all interlinked with xrefs, though, so I cannot build the book unless I manually change all of them.

* I am working on a single chapter of a very large book that takes up to 2 minutes or more to build (with publican 1/2+, which is still a huge improvement), and to view my work (to review as a draft, or to check the formatting), I would like to build a single chapter. However, due to the rigor inherited by xrefs, I cannot.

The best (and completely hypothetical) solution for these cases would be if xrefs were more like xi:includes:

For more information about firewalls, refer to <xref>
  <linkend>some_unique_id</linkend>
  <fallback>the <citetitle pubwork="section">Firewalls</citetitle> section of the Red Hat Enterprise Linux <citetitle>Security Guide</citetitle>.</fallback></xref>

I suppose technically that the mix of inline and block-level elements there wouldn't work, but that's the idea.

In lieu of such a useful construct, I am wondering if:

* there is any interest on behalf of others in building only part of a book;

* there are any suggestions for what to replace xrefs to nonexistent targets with; and,

* this is a good idea or a bad one.

This feature could be abused by users saying, "Well, if the book doesn't build because of broken xrefs, just turn on directive ignore_xrefs in publican.cfg." If this were a feature, publican could warn that it converted linkends A, B and C in X and Y chapters into ____ elements. Perhaps this could be a feature that could only be enabled on the command line, and thus could not set for entire books. I think its utility is undeniable, though, as it would save many of us time and effort. I currently cannot publish completed chapters of an overall 500+ page book I am editing (that is interlinked heavily with xrefs) without either changing all the xrefs manually in a publication branch, or writing a hack of a script that replaces these xrefs with <remark>s or some other element. I've done the latter out of necessity, but it is almost certainly better if this problem is discussed on the list, where we could perhaps come up with a single band-aid instead of many individual ones :-)

Comment 1 Bug Zapper 2010-07-30 12:41:27 UTC
This bug appears to have been reported against 'rawhide' during the Fedora 14 development cycle.
Changing version to '14'.

More information and reason for this action is here:
http://fedoraproject.org/wiki/BugZappers/HouseKeeping

Comment 2 Dana Mison 2010-08-16 04:52:32 UTC
I don't like the first usecase, I think conditionals or sets should be used for that.

However it would be a useful debugging feature to be able to build with invalid XREFs.  For example when commenting out big chunks of books to isolate the source of errors that do not report useful messages (looks at FOP pointedly).  This means of debugging is very difficult with books that have lots of XREFs.

Perhaps a command line option to disable XML validation ... that only works when debugging is enabled or when the book is in draft mode ?

Comment 3 Jeff Fearn 🐞 2010-08-19 05:03:29 UTC
Decided to do this by enabling the DocBook behaviour of replacing the content with question marks, this requires disabling validation.

Added --novalid option to build:

$ publican build --help
build
    Transform XML to other formats (pdf, html, html-single, etc)

        Options:
        --help                    Display help message
        --config=s                Use a nonstandard config file
 ... snip ...
        --novalid                 Do not run the DTD validation


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

Comment 4 Jeff Fearn 🐞 2010-08-19 05:05:04 UTC
Fall back behaviour to alternate text, as proposed in the original comment, is a feature that should be requested in the DocBook upstream.

Comment 5 Fedora Update System 2010-10-06 05:49:04 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 6 Fedora Update System 2010-10-06 05:50:21 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 7 Fedora Update System 2010-10-06 05:50:24 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 8 Fedora Update System 2010-10-08 20:40:29 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.