Bug 480721

Summary:	Banned tags and translations considerations need to be added to Users Guide
Product:	[Community] Publican	Reporter:	Jeff Fearn 🐞 <jfearn>
Component:	publican	Assignee:	Michael Hideo <mhideo>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Joshua Wulf <jwulf>
Severity:	medium	Docs Contact:
Priority:	low
Version:	2.0	CC:	lcarlon, mhideo, mmcallis, publican-list
Target Milestone:	---	Keywords:	Documentation
Target Release:	---
Hardware:	All
OS:	Linux
Whiteboard:
Fixed In Version:	1.0	Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2009-11-26 05:00:25 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Jeff Fearn 🐞 2009-01-20 05:38:23 UTC

Description of problem:
The banned tags, and attributes, should be documented in the Users Guide.

Part of this relates to translation. Section 3.3.7 Book_Name.ent contains info on why entities are bad for translation, the tags and attributes banned because of l10n issues have very similar reasoning.

Since some tags are banned because they break PDF generation it might be worth noting when these were last tested so when new versions of FOP come out someone might check to see if it's still valid to ban it.

e.g. nested tables like entrytbl ruin PDF layout, but it may be fixed in FOP sometime.

Version-Release number of selected component (if applicable):
0.40

Comment 1 Brian Forte 2009-01-20 05:50:51 UTC

Urtext for this is on the ECS wiki at <https://engineering.redhat.com/trac/ContentServices/wiki/WhichXMLTagsShouldINotUse>

Note to self: bforte also has a ready-to-roll XML version of the above stored locally:
~/documents/red hat/svn/Internal/5.0/Style_Guide/en-US/Which_XML_Tag_Should_I_Use.xml

Other notes to add to this (from irc discussions with jfearn):

All questions of the reasoning behind this aside, banning attributes like xreflabel has the following practical consequence:

<chapter id="ch03">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see >xref linkend="ch03"> for details.

Will be transformed into HTML such that the displayed text of the resultant anchor tag is and can only be ‘Chapter 3: The Secret to Eternal Life’.

That is, you can’t change the xref’s linkend title (so to speak).

Comment 2 Michael Hideo 2009-06-17 01:52:30 UTC

Hi Brian,

Can you please attach the XML file to this BZ?

- Mike

(In reply to comment #1)
> Urtext for this is on the ECS wiki at
> <https://engineering.redhat.com/trac/ContentServices/wiki/WhichXMLTagsShouldINotUse>
> 
> Note to self: bforte also has a ready-to-roll XML version of the above stored
> locally:
> ~/documents/red
> hat/svn/Internal/5.0/Style_Guide/en-US/Which_XML_Tag_Should_I_Use.xml
> 
> Other notes to add to this (from irc discussions with jfearn):
> 
> All questions of the reasoning behind this aside, banning attributes like
> xreflabel has the following practical consequence:
> 
> <chapter id="ch03">
>  <title>The Secret to Eternal Life</title>
>  <para>The secret to eternal life is…</para>
> </chapter>
> 
> [more deathless prose here]  
> 
> …see >xref linkend="ch03"> for details.
> 
> Will be transformed into HTML such that the displayed text of the resultant
> anchor tag is and can only be ‘Chapter 3: The Secret to Eternal Life’.
> 
> That is, you can’t change the xref’s linkend title (so to speak).

Comment 4 Ruediger Landmann 2009-10-13 22:40:41 UTC

Now Appendix A: Disallowed elements and attributes in the Publican Users Guide. Draft available here:

http://rlandmann.fedorapeople.org/pug/appe-Disallowed_elements_and_attributes.html

Comment 5 Fedora Update System 2009-11-18 02:19:29 UTC

publican-1.2-0.fc12 has been submitted as an update for Fedora 12.
http://admin.fedoraproject.org/updates/publican-1.2-0.fc12

Comment 6 Fedora Update System 2009-11-20 05:18:38 UTC

publican-1.2-0.fc12 has been pushed to the Fedora 12 stable repository.  If problems still persist, please make note of it in this bug report.

Comment 7 Fedora Update System 2009-11-25 14:53:46 UTC

publican-1.2-0.fc11 has been pushed to the Fedora 11 stable repository.  If problems still persist, please make note of it in this bug report.