Bug 864616 - RFE: Support setting of entities from Content Specification
RFE: Support setting of entities from Content Specification
Status: CLOSED CURRENTRELEASE
Product: PressGang CCMS
Classification: Community
Component: CSProcessor (Show other bugs)
1.1
Unspecified Unspecified
urgent Severity urgent
: ---
: 1.2
Assigned To: Lee Newson
:
Depends On:
Blocks: 1012194 1013825 1013882 1019050
  Show dependency treegraph
 
Reported: 2012-10-09 14:38 EDT by Stephen Gordon
Modified: 2013-10-17 19:49 EDT (History)
5 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
: 1013882 (view as bug list)
Environment:
Last Closed: 2013-10-17 19:49:53 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Stephen Gordon 2012-10-09 14:38:42 EDT
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.
Comment 1 Stephen Gordon 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">
Comment 2 Tim Hildred 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.
Comment 3 Joshua Wulf 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.
Comment 4 Lee Newson 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)
Comment 5 Stephen Gordon 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.
Comment 6 Lee Newson 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).
Comment 7 Ruediger Landmann 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.
Comment 8 Ruediger Landmann 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
Comment 9 Lee Newson 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
Comment 10 Ruediger Landmann 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)
Comment 11 Lee Newson 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
Comment 12 Lee Newson 2013-09-30 21:46:15 EDT
I've split this into two bugs. This one will deal with overriding the default entities (so ones used by brands) and the other BZ#1013882 will deal with additional entities that can be defined in topics (ie ones that may cause translation issues).
Comment 14 Lee Newson 2013-10-08 23:56:15 EDT
Added in 1.2-SNAPSHOT, Build 201310091335

Firstly we've implemented this slightly differently to what Steve mentioned in comment #0. We've implemented this so that it works in basically the same way as publican.cfg where whatever content you place will be added to the <book>.ent as is. The new metadata element for this RFE is "Entities".

We've also restricted this to a finite set of entities until BZ#1013882 is implemented to ensure users don't try and add their own custom entities. The list of entities are loaded from a String Constant, which will allow us to easily update the valid list if required. As it stands at the moment this is the list of entities allowed:

PRODUCT
PRODVER
PREVVER
BZPRODUCT
BZURL
BZCOMPONENT
BZVERSION
BOOKID
YEAR
HOLDER
TITLE

When building the values defined in the "Entities" metadata will have priority over any default entities that are created by the builder.

Example of the new "Entities" metadata:

Entities = [
<!ENTITY BZVERSION "3.1.0">
<!ENTITY PRODUCT "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&amp;component=&BZCOMPONENT;&amp;version=&BZVERSION;'>&BZPRODUCT;</ulink>">
]
Comment 16 Matthew Casperson 2013-10-15 01:22:02 EDT
Confirmed that the list of entities listed above can be added to the .ent file. Also confirmed that entities not in the list will generate an error.

When an entity is defined twice, Publican will use the value of the first one. I'm not sure that there is any practical use case for this, so maybe the following should generate a warning:

Entities = [
<!ENTITY TITLE "title">
<!ENTITY TITLE "title2">
]
Comment 17 Lee Newson 2013-10-15 21:28:21 EDT
Had a quick go at that this morning, however it'll need a reasonable amount of work because currently all the checks are performed by wrapping the entities in a doctype and then converting it to a DOM Document. However since it's already been parsed the Document will already overwrite the duplicate element, so we'd have to use regex or something similar to determine duplicate entities.
Comment 18 Lee Newson 2013-10-17 18:30:20 EDT
Marking this as RELEASE_PENDING and created a bug for that issue since it's a minor, non blocking issue. The bug for the duplication issue is BZ#1020557.

Note You need to log in before you can comment on or make changes to this bug.