[publican-list] [Bug 616142] New: RFC: building only part of a book by altering xrefs

[Jeffrey Fearn]

Douglas Silas wrote:
> 
> https://bugzilla.redhat.com/show_bug.cgi?id=616142
> 
> 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 :-)
> 

You could probably use conditions to achieve this.

e.g.
<book>
	<xi:include href="chapter1.xml" condition="chapter1"/>
	<xi:include href="chapter2.xml" condition="chapter2"/>
...
</book>

chapter1.xml

<chapter id="chapter_one">
<title>chapter one</title>
<para>
See <xref linkend="chapter_two" condition="chapter2"/>
</para>

chapter2.xml
<chapter id="chapter_two">
<title>chapter two</title>
<para>
If life serves you lemons, make me dessert!
</para>
...

Then in your publican.cfg you just set the conditions for the chapters 
you want included.

If you REALLY want to have an alternative text, then have two 
conditions, e.g. chapter2 to use if chapter two is set and not_chapter2 
for when chapter 2 isn't set. You could specify every chapter in the cfg 
file and prepend 'not_' to the chapters you want excluded.

e.g.

chapter1.xml

<chapter id="chapter_one">
<title>chapter one</title>
<para>
See <xref linkend="chapter_two" condition="chapter2"/><remark 
condition="not_chapter2">Link deliberately omitted for this build</remark>
</para>

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY