Bug 808103

It has been suggested that the feedback section of Fedora guides contain a link similar to:

https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&version=rawhide&component=publican-fedora

Where "version" and "component" are automatically set the the appropriate value for the guide by Publican.


Expected results:

The link to Bugzilla in the "We Need Feedback!" section of a guide would fill out the "version" and "component" fields with the correct values.

Thank you

I think this has already been suggested by me last year.  If we want to do this, and I still think it's a good idea, we need to get it changed NOW and get it in front of the translators so they can translate the changes before the next release.

Created attachment 600219 [details]
Changing the BZ URL.

I don't think this change will break translations and it only requires a new entity to be placed on all guides to make it work.  It should remove all confusion as to how to navigate in BZ as the link will select everything needed for you.

Thank you for the patch, Eric. Note that there already is an entity just for this purpose: the &BOOKID; entity, which is present in the .ent file by default. Unfortunately, it looks like Publican does not allow entities in URLs, and at least on my system, it removes all entities from the URL altogether.

Steps to reproduce:

1. Open an XML file and the following to a paragraph of your choice:

   <ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&amp;component=&BOOKID;" />

2. Change into the directory with the publican.cfg file and type the following at a shell prompt to build the book (tested with both HTML and PDF):

   publican build --lang en-US --format=html,pdf

3. Open the build in a web browser or a PDF viewer and look at the URL, in my case:

   https://bugzilla.redhat.com/enter_bug.cgi?product=&component=

I am not sure if this is a bug or a feature, but an easy solution would be to add a new entity with the link itself, something like:

<!ENTITY BUGZILLA '<ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&#37;20Documentation&amp;component=wireless-guide" />'>

(In reply to comment #4)
> Thank you for the patch, Eric. Note that there already is an entity just for
> this purpose: the &BOOKID; entity, which is present in the .ent file by

I wonder if &BOOKID; is the same as what's in BZ, though.  Good catch; that would save us a lot of time and effort.

> default. Unfortunately, it looks like Publican does not allow entities in
> URLs, and at least on my system, it removes all entities from the URL
> altogether.

Well, that's less than helpful.  :/

> I am not sure if this is a bug or a feature, but an easy solution would be
> to add a new entity with the link itself, something like:
> 
> <!ENTITY BUGZILLA '<ulink
> url="https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&#37;
> 20Documentation&amp;component=wireless-guide" />'>

So creating the entity works?  Seems like an odd way of doing it.  If it works that's great.  I think I'd like to get a read from Jeff on whether this is a feature of Publican or if it can be fixed.

(In reply to comment #5)
> I wonder if &BOOKID; is the same as what's in BZ, though.  Good catch; that
> would save us a lot of time and effort.

As far as I know, &BOOKID; is only used in Feedback.xml to identify the book in Bugzilla. Well, if this RFE gets implemented, we can always send an email to the mailing list and ask maintainers to ensure they use the proper string.

> So creating the entity works?  Seems like an odd way of doing it.  If it
> works that's great.  I think I'd like to get a read from Jeff on whether
> this is a feature of Publican or if it can be fixed.

Hi Jeff,

I am sorry for requesting information from you this way, but we would appreciate your guidance. Is there a way to use entities in URLs, or can you think of a better solution?

Thank you,
Jaromir

(In reply to comment #6)
> (In reply to comment #5)
> > I wonder if &BOOKID; is the same as what's in BZ, though.  Good catch; that
> > would save us a lot of time and effort.
> 
> As far as I know, &BOOKID; is only used in Feedback.xml to identify the book
> in Bugzilla. Well, if this RFE gets implemented, we can always send an email
> to the mailing list and ask maintainers to ensure they use the proper string.
> 
> > So creating the entity works?  Seems like an odd way of doing it.  If it
> > works that's great.  I think I'd like to get a read from Jeff on whether
> > this is a feature of Publican or if it can be fixed.
> 
> Hi Jeff,
> 
> I am sorry for requesting information from you this way, but we would
> appreciate your guidance. Is there a way to use entities in URLs,

Publican doesn't do anything with entities, XSLT handles them, so it's not possible to link the ent filed to any other logic in publican.

I don't believe XSLT allows you to use entities in attributes, so you can not have an entity in a URL.

> or can you
> think of a better solution?

You could try embedding entities inside entities to build up a big entity that contains the whole ulink.

Untested:

<!ENTITY VER "17">
<!ENTITY PROD "Fedora">
<!ENTITY COMP "book-of-fu">
<!ENTITY THELINK "<ulink url='https://bugzilla.redhat.com/enter_bug.cgi?product=&PROD;&amp;component=&COMP;'/>"

Note that entities break translation so IMO you shouldn't include any text in entities used this way.

Thank you very much, Jeff. I just verified that this works perfectly:

<!ENTITY BOOKID 'doc-Deployment_Guide'>
<!ENTITY PRODUCT 'Red Hat Enterprise Linux 6'>
<!ENTITY BUGZILLA '<ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&amp;component=&BOOKID;" />'>

Created attachment 602539 [details]
Patch replacing link with entity variable.

Here's the new patch replacing the link with an entity variable.

I've made the Security Guide entity file look like this:

<!ENTITY PRODUCT "Fedora">
<!ENTITY BOOKID "security-guide">
<!ENTITY HOLDER "Fedora Project Contributors">
<!ENTITY YEAR "2010">
<!ENTITY BUGZILLA_PRODUCT "Fedora Documentation">
<!ENTITY BUGZILLA '<ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=&BUGZILLA_PRODUCT;&amp;component=&BOOKID;" />'>

I used a separate Bugzilla product entity because it is different from the Product in Fedora.  The link works great.

We actually already have something similar in the JBoss brand package; I'll use that as a model for the changes here.

Eric, the Security Guide example you've got there is fine, except the BUGZILLA_PRODUCT entity is redundant: that's what the PRODUCT entity is for.

Added in commit d38d220..dffd5e0 -- note that the publican-fedora source is already modified in preparation for Publican 3.0, so the next update of this brand will go out after its release in Fedora.

Text of Feedback now reads:

============================================

If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product &PRODUCT; and the component &BOOKID;. The following link takes you to a pre-filled bug report for this product: &BZURL;

Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue and include some of the surrounding text so we can find and fix the problem quickly.

Document URL:


Section Number and Name:


Describe the issue:


Suggestions for improvement:


Additional information:

============================================

The expected BZURL entity should be formatted:

<!ENTITY BZURL "<ulink url='https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&amp;component=&BOOKID;'>http://bugzilla.redhat.com/</ulink>">

The only downside to this is that any brand-new book created with the publican-fedora brand will fail to build until the author provides this entity.

(In reply to comment #11)
> We actually already have something similar in the JBoss brand package; I'll
> use that as a model for the changes here.
> 
> Eric, the Security Guide example you've got there is fine, except the
> BUGZILLA_PRODUCT entity is redundant: that's what the PRODUCT entity is for.

Okay, I didn't know if &PRODUCT was being used for anything else in addition to the BZ component.

I'd remove 'typographical', since we care about content errors, too. Otherwise, this looks great.

This bug appears to have been reported against 'rawhide' during the Fedora 19 development cycle.
Changing version to '19'.

(As we did not run this process for some time, it could affect also pre-Fedora 19 development
cycle bugs. We are very sorry. It will help us with cleanup during Fedora 19 End Of Life. Thank you.)

More information and reason for this action is here:
https://fedoraproject.org/wiki/BugZappers/HouseKeeping/Fedora19

Some of our guides have:
<!ENTITY BUGZILLA '<ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&amp;component=&BOOKID;" />'>

The current version of publican-fedora needs this:
<!ENTITY BZURL "<ulink url='https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&amp;component=&BOOKID;'>http://bugzilla.redhat.com/</ulink>">

I have updated `master` for most of our guides and will apply it to branch versions as they are published.