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;&component=&BZCOMPONENT;&version=&BZVERSION;'>&BZPRODUCT;</ulink>" BOOKID "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&component=&BZCOMPONENT;&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.
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;&component=&BZCOMPONENT;&version=&BZVERSION;'>&BZPRODUCT;</ulink>"> <!ENTITY BOOKID "<ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&component=&BZCOMPONENT;&version=&BZVERSION;'>&BZCOMPONENT;</ulink>"> <!ENTITY BOOKID "Guides-REST API">
+1 Otherwise, we're doing a csprocessor assemble and then manually editing the entities file. Which is fine, but prone to human error.
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.
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)
(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.
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;&component=&BZCOMPONENT;&version=&BZVERSION;'>&BZCOMPONENT;</ulink> Entity BookID = <ulink url='&BZURL;enter_bug.cgi?product=&BZPRODUCT;&component=&BZCOMPONENT;&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).
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.
Oh, and: YEAR as well, since otherwise PressGang just uses the current year, regardless of the book's publication history
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
(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)
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
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).
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;&component=&BZCOMPONENT;&version=&BZVERSION;'>&BZPRODUCT;</ulink>"> ]
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"> ]
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.
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.