Bug 812412 - several issues from the reference guide pdf
several issues from the reference guide pdf
Status: CLOSED DEFERRED
Product: JBoss Enterprise Portal Platform 5
Classification: JBoss
Component: Documentation (Show other bugs)
5.2.1.CR02
Unspecified Unspecified
unspecified Severity unspecified
: ---
: 5.2.x
Assigned To: Jared MORGAN
Michal Vanco
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-04-13 12:05 EDT by Viliam Rockai
Modified: 2015-08-31 23:31 EDT (History)
7 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-02-10 22:16:12 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---
Commits:
8775 by jaredmorgs at 2012-07-06 01:00:36 EDT (show)
8775 by jaredmorgs at 2012-07-06 01:00:36 EDT

Checked in to /mnt/n4aphx2-3.storage.phx2.redhat.com/svn/repos/gatein

BZ#812412 cumulative minor corrections

26 files changed:

  • epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml (+28 / -61)
  • epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml (+59 / -69)
  • epp/docs/branches/5.2/Reference_Guide/en-US/images/AuthenticationAndIdentity/Overview/loginScreen.png (+0 / -0)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Advanced_Concepts.xml (+596 / -876)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml (+65 / -79)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml (+359 / -465)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml (+111 / -146)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Specific_Services.xml (+416 / -541)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml (+332 / -428)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml (+14 / -15)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml (+94 / -98)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml (+75 / -98)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml (+6 / -6)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml (+449 / -590)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/workspace-persistence-storage.xml (+84 / -107)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/data-container.xml (+429 / -553)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml (+69 / -142)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/lock-manager-config.xml (+239 / -380)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml (+36 / -49)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml (+99 / -115)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml (+155 / -206)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml (+154 / -201)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml (+379 / -508)
  • epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml (+1 / -2)
  • epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml (+2 / -2)
8776 by jaredmorgs at 2012-07-06 01:01:52 EDT (show)
8776 by jaredmorgs at 2012-07-06 01:01:52 EDT

Checked in to /mnt/n4aphx2-3.storage.phx2.redhat.com/svn/repos/gatein

BZ#812412 cumulative minor corrections

3 files changed:

  • epp/docs/branches/5.2/Reference_Guide/en-US/code_samples/jcr-configuration.xml_code (+83 / -0)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_cluster-config/indexer-config.xml_code (+12 / -0)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_lock-manager-config/lock-config.xml_code (+31 / -0)
8778 by jaredmorgs at 2012-07-08 20:39:39 EDT (show)
8778 by jaredmorgs at 2012-07-08 20:39:39 EDT

Checked in to /mnt/n4aphx2-3.storage.phx2.redhat.com/svn/repos/gatein

BZ#812412 cumulative commit

6 files changed:

  • epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/code_samples/jcr-configuration.xml_code (+0 / -83)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/jcr-configuration.xml_code (+83 / -0)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml (+399 / -559)
  • epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.ent (+3 / -3)
8779 by jaredmorgs at 2012-07-09 00:34:49 EDT (show)
8779 by jaredmorgs at 2012-07-09 00:34:49 EDT

Checked in to /mnt/n4aphx2-3.storage.phx2.redhat.com/svn/repos/gatein

BZ#812412 - Normalized the JBOSS_HOME references to EPP_HOME, and rolled in cumulative feedback from the devs as per the ticket comments.

29 files changed:

  • epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/jcr-configuration.xml (+83 / -0)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/jcr-configuration.xml_code (+0 / -83)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/PortletDevelopment_Standard/default249.java (+3 / -0)
  • epp/docs/branches/5.2/Reference_Guide/en-US/extras/PortletDevelopment_Standard/JSPHelloUserPortlet.java (+7 / -2)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Advanced_Concepts.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml (+3 / -3)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml (+3 / -4)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml (+3 / -3)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml (+58 / -81)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml (+40 / -55)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml (+1 / -1)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml (+20 / -20)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/cluster-config.xml (+166 / -219)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml (+2 / -2)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/jdbc-data-container-config.xml (+394 / -546)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml (+80 / -109)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml (+523 / -750)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml (+2 / -2)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml (+267 / -331)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml (+2 / -2)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml (+9 / -7)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml (+85 / -110)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml (+4 / -4)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml (+160 / -199)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml (+62 / -83)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml (+557 / -915)
  • epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml (+16 / -26)


Attachments (Terms of Use)

  None (edit)
Description Viliam Rockai 2012-04-13 12:05:44 EDT
taken from the pdf:
http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/5.2/pdf/Reference_Guide/JBoss_Enterprise_Portal_Platform-5.2-Reference_Guide-en-US.pdf

p10: in the example on bottom of the page the #4 is outside the border and the last line is blue instead of black. the color is blue on the p11, too.
p14-p16: the color of the ".png" extension is green and should be black.
p22: this page is blank on a purpose?
p110: the login dialogue now has the EPP letters in it and is red.
p116: the URL link has another style than other URLs in the doc. maybe it would be nice to have all the http[s]:// links clickable in the doc.
p156: ID_HOME would be nicer bold in the note on the top of the page.
p157: cells in table 17.2 are overlapping
Comment 1 Viliam Rockai 2012-04-16 11:45:04 EDT
more issues:

p265: jcr-configuration.xml looks little bit different. needs fixing. same for p267

p291-292: again, the xml has changed a bit. i guess this is the current version:
http://anonsvn.jboss.org/repos/exo-jcr/jcr/tags/1.14.6-GA/exo.jcr.component.core/src/test/resources/conf/standalone/test-configuration-jbc.xml

the InitialContextInitializer is now <target-component> and i can't see any "default-context-factory" parameter in config files

p293-294: again the xml seems not to be updated. in http://anonsvn.jboss.org/repos/exo-jcr/jcr/tags/1.14.6-GA/exo.jcr.component.core/src/test/resources/conf/standalone/test-jcr-config-jbc.xml i can see, that the lock-manager is now configured in other way.

p301: text overlaping right edge of the page

p313: lock-config.xml for clustering mode has changed, some value have moved to properties and more (diff is needed). can be found in ..WEB-INF/conf/jcr/jbosscache/cluster/lock-config.xml
same for indexer-config.xml

p316: again in portal, the value was moved to property:
              <property name="jbosscache-configuration" value="${gatein.jcr.lock.cache.config}" />

in config from the exo jcr repo (above) the value is "conf/standalone/test-jbosscache-lock.xml"

p316-320: i can't find the ' test-jbosscache-lock-config.xml' file and the 'test-jbosscache-lock.xml' looks different than the example

p326: current version of jbosscache-indexer.xml file is missing the eviction tag

p345: values in table are overlapping
Comment 2 Michal Vanco 2012-04-16 14:05:04 EDT
Ref.Guide comments:

main page
An in-depth guide to Enterprise Portal Platform 5.2.0
->
An in-depth guide to Enterprise Portal Platform 5.2.1

- update users on main page (remove Luc Texier, Wesley Hales and add new users who participate)

1.
based on the GateIn project which is the merge of two mature Java projects; JBoss Portal and eXo Portal
->
based on the GateIn project which is the merge of two mature Java projects: JBoss Portal and eXo Portal

6.1 last sentence
remove bold from "path"

6.2 after portal.xml
The defined classic portal is accessible to "Everyone" (at /portal/public/classic) but only members of the group /platform/administrators can edit it. 
->
The defined classic portal is accessible to "Everyone" (at /portal/classic) but only members of the group /platform/administrators can edit it. 

Subnodes
This element defines the parent/child relationship between a page and a subnode. 
->
This element defines the parent/child relationship between a node and a subnode. 

7.3.1 second image
- there is "daa" label on right node, but it should be called "bar" based on config file
(same for last image - overwrite mode)

Example 11.2. Example 2
/* >orientation=rt */
->
/* orientation=rt */

13.2.2. Building Controller
provide more insight into the routing engine (the findRoutes operation). see Rebuiding controller for more detail 
->
provide more insight into the routing engine (the findRoutes operation), see Rebuiding controller for more detail.

- remove next line with: > ReBuilding controller

Attribute configurationPath: the read only the configuration path of the controller xml file 
->
Attribute configurationPath: the read only configuration path of the controller xml file 

13.2.3.
- missing dots at last 2 sentences

13.3.1
The gtn:handler names is one the most important qualified name
->
The gtn:handler name is one the most important qualified name

An handler is a class
->
A handler is a class
Comment 3 Jared MORGAN 2012-04-16 16:48:54 EDT
Thanks for letting me know about these issues. I will address them in EPP 5.2.2 when I totally rework this user guide.
Comment 4 Miroslav Cupák 2012-04-17 10:58:45 EDT
Some more comments regarding the Reference Guide:

14.2.1. Deploying your first portlet
- remove "or the jboss-epp-<VERSION>-docs/epp-doc/examples/portlets directory of the documentation package"

14.2.1.1. Compiling
- gatein-simplest-helloworld-5.2.0.GA.war -> gatein-simplest-helloworld-5.2.1.GA.war

14.2.1.3. Portlet Class
- Below is the Java source for an example portlet named simplesthelloworld/src/main/java/org/jboss/portal/portlet/samples -> Below is the Java source for an example portlet named SimplestHelloWorldPortlet

No. 1 should be rephrased: 
"The javax.portlet.Portlet interface uses the javax.portlet.GenericPortlet class which implements the Portlet render method to dispatch to abstract mode-specific methods. This makes it easier to support the standard portlet modes. Portlet render also provides a default implementation for the processAction, init and destroy methods."

- The interface does not "use" GenericPortlet class. Also I guess javax.portlet.GenericPortlet was supposed to be used instead of Portlet render in the last quoted sentence, that would make more sense. 

14.2.2. JavaServer Pages Portlet Example
- remove "or the /jboss-epp-<VERSION>-docs/epp-doc/examples/portlets directory of the documentation package"

- "Compiling the example" should be a numbered subsection (like its alternative in the previous section)

- jsphellouser/target/gatein-jsp-hellouser-5.2.0.GA.war -> jsphellouser/target/gatein-jsp-hellouser-5.2.1.GA.war

14.2.2.2. Portlet Class
- numbers in the code sample break the layout of the code, which is sort of hard to read as a result
- No. 4 in the first code sample is on a wrong line
- third code sample - numbers are not on the correct lines

14.2.2.4. JSF example using the JBoss Portlet Bridge
- 14.2.2.4. JSF example using the JBoss Portlet Bridge - should be a section higher by one level as the rest of the examples, i.e. 14.2.3.

- remove "or the /jboss-epp-<VERSION>-docs/epp-doc/examples/portlets directory of the documentation package"

Chapter 15. Shared portlet.xml
- "The file path is /<JBOSS_HOME>" - the initial "/" should be dropped
Comment 5 Viliam Rockai 2012-04-17 11:20:03 EDT
p204: text overlapping table
p215: i'm unable to grep PortalContainerConfig in the element <target-component> whern greping over exo JCR sources or portal config.
p222: "After deploying you find" -> "After deploying you can find". but deploying of what? i guess the file is always there.
p224: "HashTable The RootContainer creates a java HashTable". the 1st hashtable seems redundant. but the whole paragraph seems strange to me (like the question in the middle of it).
p237: for some paths the root is not clear. i.e. what is the root of portal/trunk/web/portal/src/main/webapp/WEB-INF/conf/database/database-configuration.tmpl.xml ?
p238-p242: again questions in the text.
Comment 6 Miroslav Cupák 2012-04-17 18:38:04 EDT
16.1. JBoss Portlet Bridge Overview
- the disclaimer about JSR 329 not being final should be removed - the specification is already final

16.2.2. Bridge Frameworks and Extensions
- "JBoss Enterprise Portal Platform" should be highlighted as the rest of the technologies in the sentence

16.3.1.3.1. web.xml
- a confusing sentence - "Directs the bridge to first delegate the render only if an Exception is thrown then render the view based on its own logic." -> "Directs the bridge to first delegate the render and if and only if an exception is thrown, then render the view based on its own logic."

16.3.2.1. web.xml
- wrong configuration in the second code sample

<script src="/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script>
<script src="/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="/faces/rfRes/org/richfaces/skin.xcss"/>

should be changed to

<script src="/richFacesPortlet/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script>
<script src="/richFacesPortlet/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>

i.e. the name of the portlet (war file) should be added to the path. It should be also noted in the description that the string "richFacesPortlet" comes from there.

16.3.2.2. Configuration needed for Richfaces to work with WSRP and PortletBridge
- "Richfaces" -> "RichFaces" (in the title)

- "The styles below must also be manually added to the facelets template header in the JBOSS_HOME/portletbridge/examples/richFacesPortlet-<VERSION>.war:richFacesPortlet.war/templates/main.xhtml file." -> "The styles below must also be manually added to the facelets template header (example from richFacesPortlet.war/templates/main.xhtml in JBOSS_HOME/portletbridge/examples/)."

- errors in the second code sample

<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfResorg/richfaces/renderkit/html/css/basic_both.xcss"/>
<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfResorg/richfaces/renderkit/html/css/extended_both.xcss"/>
<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>

should be changed to

<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/basic_both.xcss"/>
<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/extended_both.xcss"/>
<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>

16.3.4.2.1. Configuration
- link should be changed to point to the current version of the bridge
"A clear and working example can be found in the Seam Booking Demo portlet. http://anonsvn.jboss.org/repos/portletbridge/tags/2.2.0.GA.EPP520/examples/seam/booking/" -> "A clear and working example can be found in the Seam Booking Demo (http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EPP521/examples/seam/booking/)."

16.3.4.3.1. Configuration
- ResourceBean.java link should point to the current tag of the bridge
http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.CR1/examples/richfaces/richfaces-demo/src/main/java/org/richfaces/demo/common/ResourceBean.java -> http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EPP521/examples/richfaces/richfaces-demo/src/main/java/org/richfaces/demo/common/ResourceBean.java

- "url served from the portlets web application" -> "URL served from the portlet application"

16.4.1. Excluding Attributes from the Bridge Request Scope
- "any attribute beginning with foo.baz(wild-card)" -> "any attribute beginning with foo.baz."
Comment 7 Jared MORGAN 2012-05-13 21:15:53 EDT
Thanks for the cover to cover review Viliam, Miroslav, and Michal.

All general formatting issues identified are cause predominantly by FOP and will be fixed when Publican 3 stops using FOP for PDF transformation. wkhtmltopdf is the default engine in Publican 3 for PDF, and is streets ahead of crappy FOP. 

I will incorporate the errors in text as prescribed.

While the Reference Guide will not be converted cover-to-cover to task-based format, those changes surrounding your fixes may be tweaked slightly as part of continuous improvement.
Comment 8 Jared MORGAN 2012-07-05 01:38:46 EDT
(In reply to comment #0)
> taken from the pdf:
> http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/5.2/pdf/
> Reference_Guide/JBoss_Enterprise_Portal_Platform-5.2-Reference_Guide-en-US.
> pdf
> 
> p10: in the example on bottom of the page the #4 is outside the border and
> the last line is blue instead of black. the color is blue on the p11, too.
> p14-p16: the color of the ".png" extension is green and should be black.
> p22: this page is blank on a purpose?
> p110: the login dialogue now has the EPP letters in it and is red.
> p116: the URL link has another style than other URLs in the doc. maybe it
> would be nice to have all the http[s]:// links clickable in the doc.
> p156: ID_HOME would be nicer bold in the note on the top of the page.
> p157: cells in table 17.2 are overlapping

Corrected the Login dialog picture on PDF page 110. 

URLs will be normalized to <ulink> elements as I do more work on this guide.
Comment 9 Jared MORGAN 2012-07-06 00:01:29 EDT
(In reply to comment #1)

Thanks for your comments Viliam. PDF page numbers are not the best mechanism to reference issues by, because page numbers can change between releases. Please reference the closest block element heading you can, like I've done in my responses and questions. Chapter and Sections headings are great. Procedure titles are even better.

It helps me out heaps if you can do it like that. :D

> more issues:
> 
> p265: jcr-configuration.xml looks little bit different. needs fixing. same
> for p267
> 
> p291-292: again, the xml has changed a bit. i guess this is the current
> version:
> http://anonsvn.jboss.org/repos/exo-jcr/jcr/tags/1.14.6-GA/exo.jcr.component.
> core/src/test/resources/conf/standalone/test-configuration-jbc.xml
> 
> the InitialContextInitializer is now <target-component> and i can't see any
> "default-context-factory" parameter in config files

22.1. Portal configuration - XML changed as prescribed.

> 
> p293-294: again the xml seems not to be updated. in
> http://anonsvn.jboss.org/repos/exo-jcr/jcr/tags/1.14.6-GA/exo.jcr.component.
> core/src/test/resources/conf/standalone/test-jcr-config-jbc.xml i can see,
> that the lock-manager is now configured in other way.

25.2. Multi-database Configuration - XML changed as prescribed.

> 
> p301: text overlaping right edge of the page

FOP issue. Can not fix.

> 
> p313: lock-config.xml for clustering mode has changed, some value have moved
> to properties and more (diff is needed). can be found in
> ..WEB-INF/conf/jcr/jbosscache/cluster/lock-config.xml
> same for indexer-config.xml

30.4.2. Lock manager template - XML changed as prescribed.

30.4.3. Query handler (indexer) template - XML changed as prescribed

> p316: again in portal, the value was moved to property:
>               <property name="jbosscache-configuration"
> value="${gatein.jcr.lock.cache.config}" />
> 
> in config from the exo jcr repo (above) the value is
> "conf/standalone/test-jbosscache-lock.xml"

I can't match your feedback to the correct section to change. PDF page 316 is now the tail end of the code sample in 30.4.3. Query handler (indexer) template. Could you please re-confirm.

> 
> p316-320: i can't find the ' test-jbosscache-lock-config.xml' file and the
> 'test-jbosscache-lock.xml' looks different than the example

Not quite sure what I should do here. Do you know of another file that might replace test-jbosscache-lock-config.xml?

> 
> p326: current version of jbosscache-indexer.xml file is missing the eviction
> tag

Are you referring to 32.2.2. Cluster-ready indexing and the code samples in there. Which one in particular?

> 
> p345: values in table are overlapping
Comment 10 Jared MORGAN 2012-07-06 00:15:09 EDT
(In reply to comment #1)

Thanks for your comments Viliam. PDF page numbers are not the best mechanism to reference issues by, because page numbers can change between releases. Please reference the closest block element heading you can, like I've done in my responses and questions. Chapter and Sections headings are great. Procedure titles are even better.

It helps me out heaps if you can do it like that. :D

> more issues:
> 
> p265: jcr-configuration.xml looks little bit different. needs fixing. same
> for p267
> 
> p291-292: again, the xml has changed a bit. i guess this is the current
> version:
> http://anonsvn.jboss.org/repos/exo-jcr/jcr/tags/1.14.6-GA/exo.jcr.component.
> core/src/test/resources/conf/standalone/test-configuration-jbc.xml
> 
> the InitialContextInitializer is now <target-component> and i can't see any
> "default-context-factory" parameter in config files

22.1. Portal configuration - XML changed as prescribed.

> 
> p293-294: again the xml seems not to be updated. in
> http://anonsvn.jboss.org/repos/exo-jcr/jcr/tags/1.14.6-GA/exo.jcr.component.
> core/src/test/resources/conf/standalone/test-jcr-config-jbc.xml i can see,
> that the lock-manager is now configured in other way.

25.2. Multi-database Configuration - XML changed as prescribed.

> 
> p301: text overlaping right edge of the page

FOP issue. Can not fix.

> 
> p313: lock-config.xml for clustering mode has changed, some value have moved
> to properties and more (diff is needed). can be found in
> ..WEB-INF/conf/jcr/jbosscache/cluster/lock-config.xml
> same for indexer-config.xml

30.4.2. Lock manager template - XML changed as prescribed.

30.4.3. Query handler (indexer) template - XML changed as prescribed

> p316: again in portal, the value was moved to property:
>               <property name="jbosscache-configuration"
> value="${gatein.jcr.lock.cache.config}" />
> 
> in config from the exo jcr repo (above) the value is
> "conf/standalone/test-jbosscache-lock.xml"

I can't match your feedback to the correct section to change. PDF page 316 is now the tail end of the code sample in 30.4.3. Query handler (indexer) template. Could you please re-confirm.

> 
> p316-320: i can't find the ' test-jbosscache-lock-config.xml' file and the
> 'test-jbosscache-lock.xml' looks different than the example

Not quite sure what I should do here. Do you know of another file that might replace test-jbosscache-lock-config.xml?

> 
> p326: current version of jbosscache-indexer.xml file is missing the eviction
> tag

Are you referring to 32.2.2. Cluster-ready indexing and the code samples in there. Which one in particular?

> 
> p345: values in table are overlapping

FOP issue. Can not fix.
Comment 11 Jared MORGAN 2012-07-09 23:16:57 EDT
(In reply to comment #2)
> Ref.Guide comments:
> 
> main page
> An in-depth guide to Enterprise Portal Platform 5.2.0
> ->
> An in-depth guide to Enterprise Portal Platform 5.2.1

Changed to 5.2 generically, and added "and its patch releases" to cater for 5.2.x releases.

> 
> - update users on main page (remove Luc Texier, Wesley Hales and add new
> users who participate)

Removed users. Will add more as directed.

> 
> 1.
> based on the GateIn project which is the merge of two mature Java projects;
> JBoss Portal and eXo Portal
> ->
> based on the GateIn project which is the merge of two mature Java projects:
> JBoss Portal and eXo Portal

Changed to:

JBoss Enterprise Portal Platform is based on the GateIn project, which is the merge of two mature Java projects: JBoss Portal and eXo Portal.

> 
> 6.1 last sentence
> remove bold from "path"

That is correctly marked-up in XML as <filename>, which it is. That formats as bold. Leaving as is.

> 
> 6.2 after portal.xml
> The defined classic portal is accessible to "Everyone" (at
> /portal/public/classic) but only members of the group
> /platform/administrators can edit it. 
> ->
> The defined classic portal is accessible to "Everyone" (at /portal/classic)
> but only members of the group /platform/administrators can edit it. 

In the "Portal Navigation" section - Incorporated.

> 
> Subnodes
> This element defines the parent/child relationship between a page and a
> subnode. 
> ->
> This element defines the parent/child relationship between a node and a
> subnode. 

In the "Portal Navigation" section - Incorporated.

> 
> 7.3.1 second image
> - there is "daa" label on right node, but it should be called "bar" based on
> config file
> (same for last image - overwrite mode)

In section "Navigation Data" - TODO RAISE BUGZILLA SEPARATE TO THIS ONE TO WORK ON FIXING THESE ISSUES.

> 
> Example 11.2. Example 2
> /* >orientation=rt */
> ->
> /* orientation=rt */

Fixed. Docs QE: Search for surrounding text "   In this example we need to modify the padding according to the orientation:"

> 
> 13.2.2. Building Controller
> provide more insight into the routing engine (the findRoutes operation). see
> Rebuiding controller for more detail 
> ->
> provide more insight into the routing engine (the findRoutes operation), see
> Rebuiding controller for more detail.
> 
> - remove next line with: > ReBuilding controller

Removed the bullet point. Docs QE, search for "changed and reloaded at runtime, this helps the testing of different configurations easily" for surrounding text verification.

> 
> Attribute configurationPath: the read only the configuration path of the
> controller xml file 
> ->
> Attribute configurationPath: the read only configuration path of the
> controller xml file 

Deleted the extra "the".

> 
> 13.2.3. Controller Configuration (controller.xml)
> - missing dots at last 2 sentences

Added colons and full-stops. Also added the three types of parameters missing from the last sentence in this section. 

> 
> 13.3.1 Routing
> The gtn:handler names is one the most important qualified name
> ->
> The gtn:handler name is one the most important qualified name
> 
> An handler is a class
> ->
> A handler is a class

Fixed both instances.
Comment 12 Jared MORGAN 2012-07-09 23:17:28 EDT
(In reply to comment #4)
> Some more comments regarding the Reference Guide:
> 
> 14.2.1. Deploying your first portlet
> - remove "or the jboss-epp-<VERSION>-docs/epp-doc/examples/portlets
> directory of the documentation package"

Removed.

> 
> 14.2.1.1. Compiling
> - gatein-simplest-helloworld-5.2.0.GA.war ->
> gatein-simplest-helloworld-5.2.1.GA.war

Updated entity controlling this value.

> 
> 14.2.1.3. Portlet Class
> - Below is the Java source for an example portlet named
> simplesthelloworld/src/main/java/org/jboss/portal/portlet/samples -> Below
> is the Java source for an example portlet named SimplestHelloWorldPortlet

Changed as prescribed.

> 
> No. 1 should be rephrased: 
> "The javax.portlet.Portlet interface uses the javax.portlet.GenericPortlet
> class which implements the Portlet render method to dispatch to abstract
> mode-specific methods. This makes it easier to support the standard portlet
> modes. Portlet render also provides a default implementation for the
> processAction, init and destroy methods."
> 
> - The interface does not "use" GenericPortlet class. Also I guess
> javax.portlet.GenericPortlet was supposed to be used instead of Portlet
> render in the last quoted sentence, that would make more sense. 

Based on info in http://www.bluesunrise.com/portlet-api/javax/portlet/GenericPortlet.html, 
I've reworded the point. Please review for accuracy.

> 
> 14.2.2. JavaServer Pages Portlet Example
> - remove "or the /jboss-epp-<VERSION>-docs/epp-doc/examples/portlets
> directory of the documentation package"

Removed.

> 
> - "Compiling the example" should be a numbered subsection (like its
> alternative in the previous section)

Reworked, and fixed.

> 
> - jsphellouser/target/gatein-jsp-hellouser-5.2.0.GA.war ->
> jsphellouser/target/gatein-jsp-hellouser-5.2.1.GA.war

Fixed.

> 
> 14.2.2.2. Portlet Class
> - numbers in the code sample break the layout of the code, which is sort of
> hard to read as a result
> - No. 4 in the first code sample is on a wrong line
> - third code sample - numbers are not on the correct lines

I've done away completely with the <programlistingco> for these code samples.
Converted them to examples, standard <programlisting> entries, and used Java comments to highlight
the correct parts of the example. Let me know if this will cause issues if people copy-paste.
I don't know of any other way of correcting line callouts specifically, apart from this solution.

> 
> 14.2.2.4. JSF example using the JBoss Portlet Bridge
> - 14.2.2.4. JSF example using the JBoss Portlet Bridge - should be a section
> higher by one level as the rest of the examples, i.e. 14.2.3.

Promoted one section higher.

> 
> - remove "or the /jboss-epp-<VERSION>-docs/epp-doc/examples/portlets
> directory of the documentation package"
> 
> Chapter 15. Shared portlet.xml
> - "The file path is /<JBOSS_HOME>" - the initial "/" should be dropped

Fixed.
Comment 13 Jared MORGAN 2012-07-09 23:19:04 EDT
(In reply to comment #5)
> p204: text overlapping table

Manually broke classname with a space.

> p215: i'm unable to grep PortalContainerConfig in the element
> <target-component> whern greping over exo JCR sources or portal config.

NEEDINFO: Who would I ask to determine the corect XML config in this section (which for Docs QE happens to be 19.3.5.1.1. AddDependencies)

> p222: "After deploying you find" -> "After deploying you can find". but
> deploying of what? i guess the file is always there.

I've reworked this paragraph, and marked up the elements that were just formatted as words (they got lost in the text). Docs QE, search for "All custom configuration is made in the". The change is in the "Components" section.

> p224: "HashTable The RootContainer creates a java HashTable". the 1st
> hashtable seems redundant. but the whole paragraph seems strange to me (like
> the question in the middle of it).

I've removed the redundant text. This whole chapter needs to be reworked. It's a mess, from an information structure perspective.

NEEDINFO This seciton refers to exo-tomcat/exo-conf.  I don't know whether this is suggesting it only applies to stand-alone, non-supported versions. Can you make sense of it.

> p237: for some paths the root is not clear. i.e. what is the root of
> portal/trunk/web/portal/src/main/webapp/WEB-INF/conf/database/database-
> configuration.tmpl.xml ?
> p238-p242: again questions in the text.

I need to go through this guide and check all paths are correct. Many are not absolute paths. Making another ticket for this, as it will be a big job. I'll need to download the platform and unpack it so I can verify the paths.

TODO Make BZ to validate all paths in document.
Comment 14 Jared MORGAN 2012-07-09 23:24:36 EDT
(In reply to comment #6)
> 16.1. JBoss Portlet Bridge Overview
> - the disclaimer about JSR 329 not being final should be removed - the
> specification is already final

Removed Disclaimer.

> 
> 16.2.2. Bridge Frameworks and Extensions
> - "JBoss Enterprise Portal Platform" should be highlighted as the rest of
> the technologies in the sentence

Done.

> 
> 16.3.1.3.1. web.xml
> - a confusing sentence - "Directs the bridge to first delegate the render
> only if an Exception is thrown then render the view based on its own logic."
> -> "Directs the bridge to first delegate the render and if and only if an
> exception is thrown, then render the view based on its own logic."

Changed to "Directs the bridge to first delegate the render. If an exception is thrown, the bridge renders the view based on its own logic."

> 
> 16.3.2.1. web.xml
> - wrong configuration in the second code sample
> 
> <script src="/faces/rfRes/org/ajax4jsf/framework.pack.js"
> type="text/javascript"></script>
> <script src="/faces/rfRes/org/richfaces/ui.pack.js"
> type="text/javascript"></script>
> <link rel="stylesheet" type="text/css"
> href="/faces/rfRes/org/richfaces/skin.xcss"/>
> 
> should be changed to
> 
> <script src="/richFacesPortlet/faces/rfRes/org/ajax4jsf/framework.pack.js"
> type="text/javascript"></script>
> <script src="/richFacesPortlet/faces/rfRes/org/richfaces/ui.pack.js"
> type="text/javascript"></script>
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>
> 
> i.e. the name of the portlet (war file) should be added to the path. It
> should be also noted in the description that the string "richFacesPortlet"
> comes from there.

Understood. I have made the distinction that "richFacesPortlet" is replaceable text and should be appropriately substituted.

> 
> 16.3.2.2. Configuration needed for Richfaces to work with WSRP and
> PortletBridge
> - "Richfaces" -> "RichFaces" (in the title)

Changed title to active voice "Configure RichFaces to work with WSRP and PortletBridge", which flows on to the next feedback item below.

> 
> - "The styles below must also be manually added to the facelets template
> header in the
> JBOSS_HOME/portletbridge/examples/richFacesPortlet-<VERSION>.war:
> richFacesPortlet.war/templates/main.xhtml file." -> "The styles below must
> also be manually added to the facelets template header (example from
> richFacesPortlet.war/templates/main.xhtml in
> JBOSS_HOME/portletbridge/examples/)."
> 
> - errors in the second code sample
> 
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfResorg/richfaces/renderkit/html/css/
> basic_both.xcss"/>
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfResorg/richfaces/renderkit/html/css/
> extended_both.xcss"/>
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>
> 
> should be changed to
> 
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/
> basic_both.xcss"/>
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/
> extended_both.xcss"/>
> <link rel="stylesheet" type="text/css"
> href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>

Changed as prescribed.

> 
> 16.3.4.2.1. Configuration
> - link should be changed to point to the current version of the bridge
> "A clear and working example can be found in the Seam Booking Demo portlet.
> http://anonsvn.jboss.org/repos/portletbridge/tags/2.2.0.GA.EPP520/examples/
> seam/booking/" -> "A clear and working example can be found in the Seam
> Booking Demo
> (http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EPP521/
> examples/seam/booking/)."

Updated as prescribed.

> 
> 16.3.4.3.1. Configuration
> - ResourceBean.java link should point to the current tag of the bridge
> http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.CR1/examples/
> richfaces/richfaces-demo/src/main/java/org/richfaces/demo/common/
> ResourceBean.java ->
> http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EPP521/examples/richfaces/richfaces-demo/src/main/java/org/richfaces/demo/common/ResourceBean.java

Changed as prescribed.

> 
> - "url served from the portlets web application" -> "URL served from the
> portlet application"

Changed as prescribed.

> 
> 16.4.1. Excluding Attributes from the Bridge Request Scope
> - "any attribute beginning with foo.baz(wild-card)" -> "any attribute
> beginning with foo.baz."

Added separating dot.
Comment 15 Jared MORGAN 2012-07-10 01:51:42 EDT
Package: 

JBoss_Enterprise_Portal_Platform-Reference_Guide-5.2-web-en-US-5.2.2-6.el6eng

Link: 

http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/5.2/html-single/Reference_Guide/index.html

Changelog:

* Tue Jul 10 2012 Jared Morgan <> - 5.2.2-6
- BZ#812412 - Extensive peer review comments incorporated. Book-wide spell-check run.

Remarks: 

Stage email received, and should appear shortly.

Incorporations start at Comment#8. Docs QE, if you see a NEEDINFO, or TODO, they are notes for me and require no review by you guys. Treat those fixes as "coming in a future version".

Also note that because FOP is causing this book to not built, I have disabled PDF builds during development phase. When Publican 3 is released, I will restage the book with PDF builds enabled. 

Most text overrun issues and display and presentation issues identified by the devs were because of FOP, so these have been annotated as appropriate.
Comment 19 Jared MORGAN 2013-02-10 22:16:12 EST
Deferring this until we decide to release a new version of EPP 5.2.

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