Bug 793192 (JBEPP-276)

Current build of Reference guide can be viewed/downloaded from:
http://downtown.englab.bne.redhat.com/drafts/JBoss_Enterprise_Portal_Platform/5.0_Beta/Enterprise_Portal_Platform_Reference_Guide/

SVN:
http://svn.jboss.org/repos/gatein/portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide

QE of this document is being undertaken by Andrerw Ross on:
Monday 26th and Tuesday 27th April

To allow time for editing all feedback on this issue must be received BEFORE Thursday 22rd April

Doc TODO Notes:

Tags:
        Switch out <sect*> tags for <section> tags for continuity and numbering
	Ensure <title> is in place, remove any <para> inside <example>
	Check sect/chap ids (maybe publican clean_ids on a backup copy to see the changes)

Images:
	Switch out all scalefit="1" attributes to scale="100"
	Ensure all screencaps are RH appropriate.

Entities:
	Ensure correct definitions for PRODUCT_NAME PRODUCT_VERSION and WSRP_VERSION entities
	Ensure the correct use of PRODUCT, VERSION, PRODUCT_NAME and PRODUCT_VERSION entities throughout doc.

SVN
	Branch doc?

Link: Added: This issue related JBEPP-323

Thanks for your awesome work Thomas. Much appreciated.

I was looking at ref guide http://downtown.englab.bne.redhat.com/drafts/JBoss_Enterprise_Portal_Platform/5.0_Beta/Enterprise_Portal_Platform_Installation_Guide/html-single/#id2969831 dated May 7, in create database command, it mentions gatein-jcr which does not work with mysql. A "-" is not allowed in name. However, resulting list of database is correct. 

Currently triaging sections in Section 17 based on content quality. Will email both a pre-triage and post-triage pdf for review.

Not committing triage changes to svn until feedback is received.

Section "11.2.2. JavaServer Pages Portlet Example":
1.) I don't know nothing about JSPHeloUser, seems there is nothing like this bundled with EPP5. (And I have no idea where to look for them)
2.) part "Compiling the example"... there is not true that there need only copy *.war file into deploy directory. Since GateIn is used instead of JBoss Portal, there is no 'autodeploy/autoinstall' feature, so if someone deploy his app to $JBOSS_HOME/server/${configuration}/deploy, no link automatically appear in Portal menu. (As it was in JBoss Portal). There is need to add steps (or link to this steps) for installation examples deployed in JBoss Server deploy directory.

Attaching notes from Ref. Guide verification.

I verified doc from beginning to the end of PART I (in pdf: pages 1-63) + WSRP (chapter 15, in pdf: pages 133-152)

Everything is mentioned in notes.
I'm also attaching 4 config files which are shown in doc and are not correct (it is also described in notes)

Attachment: Added: Ref_guide_part_I_and_WSRP_verification.txt
Attachment: Added: configuration_files.zip

In attachement are notes for reference guide - Part 2 (Chapter 11, Chapter 13, Chapter 14).

So till now, We went through almost whole reference guide and remaining chapters are only:

Chapter 12 - Building JSF Portlet
Chapter 16 - Foundations
Chapter 17 - eXoJCR

We will provide the rest as soon as possible. But I have question: Is Part 3 finished and ready for our review or you are still working on it? Because today Viliam noticed really big number of typos and typographic inconsistencies, especially in chapter 17.

Attachment: Added: reference-guide-bugs-part2.txt

Section "11.2.2.4. JSF example using the JBoss Portlet Bridge"
1.) PortletBridge examples are places in "portletbridge/examples" folder instead of "examples" folder.
2.) No example "JSFHelloUser" is bundled with EPP5 (I don't know nothing about this example). Do we really have this example at all?

Section: "12.2.5. Video Tutorials"
There is a bad link labeled: "Episode 5: GateIn JMX Metrics and Dashboard Demo". This link should point to "http://www.vimeo.com/8752541" instead of "http://www.vimeo.com/7255033" which is link for previous episode (No. 4)

I tackled most of the first list of modifications.

my notes to part III, reference guide

Attachment: Added: epp_refguide_notes.txt

Committed revision 3113.

- Commit includes minor section triage.
- Section changes to re-format 4- and 5-level deep sectioning (section 17)  
- Edits as per Michal Vanco's verification attachment.

Luc, Thomas - If these changes interfere with your review of section 17, revert to r3100 as per svn log (although this will undo some QE verfication edits).

I'm recommending triage of sections 17.12 (Transactions), 17.13 (TransactionManagerLookup) and possibly 17.14 (eXo JCR Statistics) due to inadequate content.
Does anyone have any comments or objections? 

The latest version of the Reference Guide has been committed. Find it at the Hudson URL above.

This revision completes the first pass edits and included as much of the QE feedback as ECS is able to complete. Outstanding issues (from various feedback sources) are listed below:
________________________________________________________________________________________
*Apply changes from Chris's commit no. 31061 3107!!!! 
(Not sure what this means - SM)

*7.2.5 Debugging resources??? 
(Not sure what this means - SM)

*this discuss about eXo JCR standalone configuration. is it the subject of EPP5 reference guide?
(I can comment refernces to this out if nobody deems it necessary -SM)

*Villiam mentioned the variance in file paths are formatted. I found the following examples:

02portal.war/WEB-INF/conf/portal/portal/classic/portal.xml

WEB-INF/gatein-resources.xml

01eXoResources.war/WEB-INF/gatein-resources.xml

$JBOSS_HOME/bin/run.sh

eXoGadgets.war/WEB-INF/

web.war/WEB-INF/classes/locale/portlet/portal

WEB-INF/classes/locale/portlet/gadget/GadgetPortlet.

/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css 

/GateInResources/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle-rt.gif

/portletbridge/examples/

We definitely need a consistent style. We just need someone to choose one. I'm in favour of starting them all with /$PORTAL_HOME/blah/blah/
_________________________________________________________________________________________

Anything I've missed?

Major additions and changes to the document are marked with comments in the XML code for reference.

*Apply changes from Chris's commit no. 3106 3107!!!! 
(Not sure what this means - SM) 
I've done it, some were already done. What it meant it that Chris fixed in the project SVN with revision 3106 and 3107 and those changes needed to be applied on the product doc.

Hi Scott,

I am not sure if you missed our comments to Part II (chapter 11 - chapter 15) or you are planning to work on this. My comments are in attachement ( reference-guide-bugs-part2.txt ) and there are some comments from Jan Jamrich in this Jira, which are related to chapter 12 and chapter 11 (please ignore Jan's notes about missing examples in chapter 11. He didn't know that examples for simplesthelloworld, jsphelloworld, jsfhelloworld and idmhelloworld are packed in docs.zip, which is mentioned in my attachement reference-guide-bugs-part2.txt ).

A new version of the Reference Guide has been committed which incorporates many QE changes and a new OrganizationServiceClassDiagram.png image.

Remaining issues (AFAIK):

________________From Brno QE:_______________
Debugging resources???
(still not sure what this means - SM)

$base:directory - not uniform start of the path, should be changed to be uniform in the whole document
(Still working on this. Many files are in different locations; path shortening/homogenizing will be difficult. - SM)

Repository Service Configuration is describing elements and attributes used in the example configuration files. the document is not styled, tags are not distinguished from attributes and so on
(Marked as DOC TODO for next release - SM)

_______________From BNE QE:____________
Foundations.xml :
Only officially documented services should be accessed this way, and used according to documentation, as most of the services are an implementation detail of Exo, and subject to change without notice.
(Unsure why anross drew attention to this warning box. Will confirm with him asap- SM)

_________________General___________________
* Which other contributors should be named in the Ref Guide Author Group?

* Gadgets sections 13.1.1 to 13.1.7  seem very incomplete.

I am still seeing that my notes for Chapter 14 (Authentication and identity) from attachement reference-guide-bugs-part2.txt are not covered in ref guide. I went through http://downtown.englab.bne.redhat.com/drafts/JBoss_Enterprise_Portal_Platform/5.0_Beta/Enterprise_Portal_Platform_Reference_Guide/html-single/ and through source codes after your last commit (rev 3163)

Second verification notes for edited parts of Ref. Guide. 
I stated my previous note about debugging resources (I did typo in section number, sorry).
There are formatting problems with config files at 6.2, 6.4.

See attachment for more details.

Attachment: Added: Ref_guide_part_I_and_WSRP_verification2.txt

I did a review of chapter 11 (Portlet primer) again after yesterday update. My comments attached in refGuide-chapter11-update.txt .

Attachment: Added: refGuide-chapter11-update.txt

just few comments to the actual pdf version:
p158
it is said, that "K" or "KB" are the possible number formats but in examples i can see "Kbytes"
the definition is:
K or KB for kiloBytes (no need to capitalize B when the whole word "byte" is typed)
the text is:
200k or 200 KBytes
but maybe the intention was that it should be "200k for 200 KBytes" or "200k or 200 KB"

p169
reference for apache dbcp configuration has it's number in upper index (1), but i can't see the reference under the line in the bottom of the page

p179
text overflowing table - multiple times in that table

p213
missing table headers

During 2nd review of Chapter 12 I found another (small) issue with XML code snippet. See attachment

Attachment: Added: EPP5-docs-review(2nd)-Chapter12-PBR

Scott,

I just noticed the mistake in my report to chapter11 ( refGuide-chapter11-update.txt ) which has incorrect location of portlets in docs package. Correct locations of portlet examples:
In src package: /jboss-epp-5.0-src/portal/examples/portlets/
In doc package: /jboss-epp-5.0-docs/epp-doc/examples/portlets/

Latest Reference Guide edits committed. Solved XML layout problem in included config files. Adjusted column widths in Section 17.5 to correct overflow issues. Various minor edits.

Outstanding issues:

Section 11.2.2.3
- Sentence "My name is GateIn Portal. What's yours?" In example is used: "My name is JBoss Portal". But this is not issue in documentation, because "My name is JBoss Portal" should not be used
(SM - Unable to get the example portlet running so cannot update screenshot if portlet has been updated to correct wording.

Section 7.5.2
Debugging resources - magic locale??? (I have never seen this before and I don't know if it's even possible, it is great and there should be better description how to do it)
(SM - Further information unavailable at the moment. Section commented out and marked for next release)

Section 14.3.1.
Configuration of org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl - This service has one more option "useJTA" which is not mentioned in reference guide.
(SM - Added to useJTA to relevant list. No information regarding option included here, so content inferred from context referencing cacheconfig options)

Scott,

Many thanks for the updates. I just checked and I founded only minor issues in your last update. Here is the list:

11.2.1 -- typo in 3rd sentence (path to documentation package): "boss-epp-5.0-docs/epp-doc/examples/portlets" --- Typo in first word. It should be "jboss-epp-5.0-docs/epp-doc/examples/portlets"

11.2.1.2 -- Package name is not updated in the diagram (Here is still "org/gatein/portal/examples/portlets" but it should be "org/jboss/portal/portlet/samples" )

11.2.2 -- Similar typo as in 11.2.1 -- "boss-epp-5.0-docs/epp-doc/examples/portlets"

11.2.2.1 and 11.2.2.2 -- package is not updated in diagram, java class and in portlet.xml. Reference guide references to package "org/gatein/portal/examples/portlets" but correct package for example is "org/jboss/portal/portlet/samples". 

14.3.1 Option "useJTA" - This is boolean option, which determines whether JTA (Java Transaction API) will be used in Picketlink IDM.

Thanks Scott!

This JIRA resolved and remaining reference guide issues will be reported in https://jira.jboss.org/browse/JBEPP-370, which is ref. guide JIRA for EPP 5.0.1