Description of problem: I have a document with this preamble: --- <?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE article [ <!ENTITY % BOOK_ENTITIES SYSTEM "Ueberwachung_von_Transaktionen.ent"> %BOOK_ENTITIES; <!ENTITY % XCOM_ENTITIES SYSTEM "/usr/share/publican/Common_Content/XCOM/de-DE/entitiesxcom.ent"> %XCOM_ENTITIES; <!ENTITY % sgml.features "IGNORE"> <!ENTITY % xml.features "INCLUDE"> <!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod"> %DOCBOOK_ENTS; ]> <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="de"> Version-Release number of selected component (if applicable): [My content] </article/> The global entityfile is placed in /usr/share/publican/Common_Content/XCOM/de-DE/entitiesxcom.ent. It is available and valid. If i'm working inside Oxygen Editor the all entities will be solved. So the Editor shows me "Microsoft Excel" instead of &ex;. But if i'm running publican build --langs=de-DE --formats=pdf --allow_network it shows me: Beginning work on de-DE FATAL ERROR 3: parser:27 in Ueberwachung_von_Transaktionen.xml on line 437: Entity 'ex' not defined at /usr/bin/publican line 1223. How reproducible: 100% Steps to Reproduce: 1. Add a gloabal entitiy file to Common_Content 2. Reference to it in the preamble 3. Run publican build --langs=de-DE --formats=pdf --allow_network Actual results: FATAL ERROR Expected results: Building PDF Additional info: Running on a Ubuntu 14.10 with publican version 4.2.6
There is no ability in Publican to add arbitrary entity files, this was a deliberate decision taken a long time ago because using entities in documentation breaks translation. I guess we could review that if someone can present a good rebuttal to the arguments presented in the PUG [1]. 1: https://jfearn.fedorapeople.org/en-US/Publican/4.2/html/Users_Guide/chap-Publican-Users_Guide-Creating_a_document.html#sect-Publican-Users_Guide-Entities_and_translation
I can understand why you decided so. From translators pov it is bad to use entities. But we have different usecases. In my case i'm producing each day new documents in different formats but in one language (It isn't english ;-) ). The thing is that XML itself provides entities. So the usage should technicaly not so difficult. Also my usecase is that i have each day to do with many Acronyms which should be expanded in each document. I'm inside the financial sector so SEPA is the shortest acronym. To define it for each document is too slow. ATM i'm appending the stuff from the global entities to the local *.ent file. But if a new acronym is needed or anything has renamed like the TARGET Saldos from the European Central Bank to the TARGET2-System. In such thing i have to modify all already created local entity files. So in short: We have sure the usecase with translators, but also usecases for documentation in one language but the goal to have a consistent label? (not sure if this is the right word) for different entities. It would really great if you can prepare publican for respecting a global entity file.
What I'll do for this is add an option --noclean which will skip the use of Publican::XmlClean and just use the XML as provided. This will mean that all entity files will need to be specified in any file using them. Currently XmlClean will add DoBook4 entity file to DocBook5 content so the old entities work. Anyone wanting to use them and this option will have to pull in the appropriate entity file. Currently XmlClean will add $mainfile.ent to the file if it exists, anyone wanting to use that file and this option will have to add the declaration to any XML file using entities in that file. This option will not work with translations as that will require reworking XmlClean which I don't have time for ATM. Anyone wanting this feature to work with translations should open another bug and be prepared to wait. The use and behaviour of Common Content will not change.
Added --no_clean option. To ssh://git.fedorahosted.org/git/publican.git b86bbba..3d764a0 devel -> devel [Users_Guide]$ publican build --help | grep no_clean --no_clean Do not use the XML cleaner, use the XML as provided. WARNING: Will be ignored for translations! [Users_Guide]$ publican build --formats html --langs en-US --quiet FATAL ERROR 3: parser:27 in Book_Info.xml on line 12: Entity 'PANTS' not defined at /usr/bin/publican line 1225. [Users_Guide]$ echo "$?" 2 [Users_Guide]$ publican build --formats html --langs en-US --quiet --no_clean [Users_Guide]$ echo "$?" 0
Oh note, one limitation of this is that SYSTEM entries with relative paths need to be defined before PUBLIC entries. This is because the base gets changed and relative paths will be based off the wrong base path. It's might be a bug in XML::TreeBuilder, XML::Catalog, or XML::Parser.