Bug 1013882

+++ This bug was initially created as a clone of Bug #864616 +++

Splitting this bug to deal with adding additional entities that aren't in the default list. These would be entities that can be used in topics to define for example the product name, so that's much easier to change.

Description of problem:

I would like to be able to set entities from the content specification in a similar manner to that used for setting publican.cfg values. The values would be added to the end of the <bookname>.ent file in the assembly.

The exception would be that where one of the manually set entities has the same name as an automatically generated entity (regardless of whether generated by publican or csprocessor) then the automatically generated one should be removed from the file. In this manner it would be possible to override automatically generated entities.

In particularly I envisage being able to put the following in the content specification:

bookname.ent = [
BZVERSION "3.1.0"
PRODUCT "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZPRODUCT;</ulink>"
BOOKID "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZCOMPONENT;</ulink>"
]

This allows the inclusion of bugzilla links in Feedback.xml without overriding the Feedback.xml (including translations) provided by common content. Note in particular that it relies on existing BZURL, BZPRODUCT and BZCOMPONENT entities set by csprocessor, so implicitly assumes it's included after these "default" entries.

The problem we are trying to work around here is that:

- Our &PRODUCT; and &BZPRODUCT; names are not the same.
- Common_Content/Feedback.xml for the Red Hat brand uses &PRODUCT; and &BOOKID;.
- We want to use Common_Content/Feedback.xml as is rather than override it in each book.

Currently we can fix up the entities file manually before we brew, but being able to add it to the cspec would make it a once off effort and also remove the risk of someone forgetting to do this when doing a maintenance update later.

--- Additional comment from Stephen Gordon on 2012-10-09 14:51:28 EDT ---

Oh yeah, it was implied in my example but to be explicit: it is expected that the csprocessor would transform the representation from the content specification into "proper" XML entities like so:

<!ENTITY BZVERSION "3.1.0">
<!ENTITY PRODUCT "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZPRODUCT;</ulink>">
<!ENTITY BOOKID "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZCOMPONENT;</ulink>">
<!ENTITY BOOKID "Guides-REST API">

--- Additional comment from Tim Hildred on 2012-10-09 20:37:35 EDT ---

+1

Otherwise, we're doing a
csprocessor assemble

and then manually editing the entities file. Which is fine, but prone to human error.

--- Additional comment from Joshua Wulf on 2013-05-01 22:11:37 EDT ---

On the Test Star you can now inject a custom Revision History and Entities file:

Add the following Death Star directives to your Content Spec:
 
#_DSD:REVISION HISTORY = [topic ID]
#_DSD:ENTITY FILE = [topic ID]
 
The Revision History topic should be a complete appendix, just like a normal Revision History file. When you do a one-click publish the latest Revision History entry is updated with the latest package in Brew version number +1, so you're good to go.
 
Code:
 
Revision  History injection: https://github.com/jwulf/node-deathstar/blob/assembly-refactor/lib/assembler.js#L282

Entity File injection: https://github.com/jwulf/node-deathstar/blob/assembly-refactor/lib/assembler.js#L400
 
Custom Revision Histories have an editor link injected and the Death Star editor correctly renders and validates them as a Docbook appendix.

--- Additional comment from Lee Newson on 2013-05-21 20:30:43 EDT ---

Using entities should be avoided as they cause translation issues. Overriding the default values might be okay but that would have to be investigated.

I suspect what might be better here, looking at old books is to have those defaults be a ulink instead of just plain text. Another thing that would help is if the brands actually used the same components (ie RedHat uses &PRODUCT;, while JBoss uses &BZPRODUCT; for the Bugzilla Product)

--- Additional comment from Stephen Gordon on 2013-05-21 23:01:57 EDT ---

(In reply to Lee Newson from comment #4)
> Using entities should be avoided as they cause translation issues.
> Overriding the default values might be okay but that would have to be
> investigated.

While in principle I agree we are talking here about setting two entities (BOOKID and PRODUCT - or the later equivalent, BZPRODUCT, for JBoss) that are in every book produced by ECS since Publican was introduced if not before then. The reason they exist as I understand it is to allow books to rely on Feedback.xml (and associated translations) from Common_Content - thus in this case the use of the entities is seen as the lesser of two evils (though perhaps this needs to be re-evaluated given the progress made on translation memory at this point).

> I suspect what might be better here, looking at old books is to have those
> defaults be a ulink instead of just plain text. Another thing that would
> help is if the brands actually used the same components (ie RedHat uses
> &PRODUCT;, while JBoss uses &BZPRODUCT; for the Bugzilla Product)

Another gotcha here is that not all products have a public Bugzilla product (this included RHEV until very recently). That is why in some books there is instead an "identifier" to refer to in an email reporting an issue (admittedly these cases likely have to override Feedback.xml anyway in which case it's a bit of a moot point, they might have used the entities traditionally but could just as easily hard code in the future).

With regards to the BZPRODUCT thing as I implied above PRODUCT was always used by Publican, you'd have to ask someone from Middleware what the driver for changing it in that brand was.

--- Additional comment from Lee Newson on 2013-06-25 23:18:45 EDT ---

The following is primarily just a thought atm, but I thought I'd place it out there for criticism. We generally don't want anyone using entities due to the localisation issues (though BZ #978119 would likely solve that), so instead of specifying a list of entities I believe having metadata that allows you to specify the values for the default entities would be a better alternative. ie something like the following:

Entity Product = <ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZCOMPONENT;</ulink>
Entity BookID = <ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZPRODUCT;</ulink>
Entity Title = Something

In saying all that, the above becomes obsolete if the RFE I mentioned earlier is put into place (which is also why I'm marking the RFE as a dependency to this bug).

--- Additional comment from Ruediger Landmann on 2013-09-25 07:26:24 EDT ---

Regardless of mechanism, support for:

PRODUCT
PRODVER
PREVVER
BOOKID

is urgently required now for platform documentation, either hardcoded like the JBoss feedback entities are, or free-form like Steve suggests in comment 1

I'd venture that the mechanism Steve describes is still sufficiently cumbersome to discourage entity proliferation.

--- Additional comment from Ruediger Landmann on 2013-09-25 07:41:54 EDT ---

Oh, and:

YEAR

as well, since otherwise PressGang just uses the current year, regardless of the book's publication history

--- Additional comment from Lee Newson on 2013-09-25 18:48:19 EDT ---

Definitely agree that the defaults and ones mentioned by Rudi should be customisable, its others that may be used in topics that are the issue with using entities. Also Year can be customised with the "Copyright Year" metadata attribute. eg:

Copyright Year = 2010, 2012-2013

--- Additional comment from Ruediger Landmann on 2013-09-30 01:03:07 EDT ---

(In reply to Lee Newson from comment #9)
> Definitely agree that the defaults and ones mentioned by Rudi should be
> customisable, its others that may be used in topics that are the issue with
> using entities. Also Year can be customised with the "Copyright Year"
> metadata attribute. eg:
> 
> Copyright Year = 2010, 2012-2013

Where's that set from? (I can't find it in the docs)

--- Additional comment from Lee Newson on 2013-09-30 01:09:34 EDT ---

I suspect it hasn't been documented, but it has been available since csprocessor 0.30.0 (so April this year). Anyways it is just a MetaData element, so it goes anywhere at the top of a content spec.

eg:

Title = My Book
Product = My Product
Copyright Holder = Red Hat, Inc.
Copyright Year = 2010, 2012-2013