Mantis - Documentation
Viewing Issue Advanced Details
ID: Category: Severity: Reproducibility: Date Submitted: Last Update:
3450 minor always 04-17-09 07:12 04-30-09 15:34
Reporter: pablorg Platform:  
Assigned To: OS:  
Priority: normal OS Version:  
Status: new Product Version: 3.2.1  
Product Build: Resolution: open  
Projection: none      
ETA: none Fixed in Version:  
Summary: 0003450: Inconsistent Documentation
Description: Your documentation makes me doubt whether Resin is the right product for us. Quercus is very promising, but despite the client list that Resin boasts, the shoddy documentation leaves us with a bad impression.

Since source is available, it is possible to figure this all out eventually. But it's a hassle and one never knows if it's alright to trust the docs.

Specific examples:
1. Under <session-config>, use-persistent-store is not fully explained. How do I specify the store location/type? (jdbc/file)? If I click on http://localhost:8080/resin-doc/doc/resin.xtp#persistent-store, [^] I get nowhere and the navigation links/TOC on the left disappear.

2. jvm-arg is only ever mentioned in the command-line configuration section. Meanwhile, it is not a command-line configuration at all. We are not told if it is a child of <cluster> or if it can be a child of <resin> directly.

3. the links on the left side (for navigating docs) change all the time in surprising and inconsistent ways.
Steps To Reproduce:
Additional Information:
Relationships
Attached Files:

Notes
(0003960)
pablorg   
04-19-09 06:01   
More examples:

http://wiki.caucho.com/Install_FAQ [^]
Under the first question, numeral 2: $RESIN_HOME/ext-lib vs $RESIN_HOME/extlib

Under the second question: So Resin can run without the JNI libraries, it just won't be as fast as Resin.
(0003961)
pablorg   
04-19-09 06:10   
There is also NO documentation for resin 3.2

Even if you're running resin 3.2 and use the resin-doc application, you get resin 3.1 documentation that includes things such as this (which are not accurate) (also to be found in http://caucho.com/resin-3.1/doc/resin-web-server.xtp#Windows): [^]

C:\win32> resin-3.2.0\bin\resin.exe
(0003962)
pablorg   
04-19-09 06:30   
Here's another one:

http://caucho.com/resin-3.1/doc/resin-web-server.xtp#script [^]
The example shows a -resin-root parameter. If you try to use that, you get an error and this:

unknown argument '-resin-root'

usage: java -jar resin.jar [-options] [status | start | stop | restart | kill | shutdown]

where options include:
   -conf <file> : select a configuration file
   -dynamic-server <cluster:address:port> : initialize a dynamic server
   -log-directory <dir> : select a logging directory
   -resin-home <dir> : select a resin home directory
   -root-directory <dir> : select a root directory
   -server <id> : select a <server> to run
   -watchdog-port <port> : override the watchdog-port
   -verbose : print verbose starting information
(0003963)
pablorg   
04-19-09 06:35   
http://caucho.com/resin-3.1/doc/linux-boot.xtp [^]

makes reference to a bin/wrapper.pl that does not exist. It seems this is very old, crufty documentation. Do you guys see a future for Resin or are you just letting it rot on the vine?
(0003975)
pablorg   
04-30-09 15:34   
here's more inconsistent documentation from the resin 4 quercus docs:

this example is given, yet it seems incorrect (jndi name)

Example: overriding database configuration in resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin"> [^]
  <database jndi-name="jdbc/mysql">
    <driver type="org.gjt.mm.mysql.Driver">
      <url>jdbc:mysql://localhost:3306/test</url> [^]
      <user></user>
      <password></password>
    </driver>
  </database>

  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <database>java:comp/env/jdbc/myDatabaseName</database>
    </init>
  </servlet-mapping>
</web-app>