[opencms-dev] another issue -- An FAQ for this mailing list

[Paul D. Bain]

Joe Desbonnet wrote:
> Yes, an FAQ is a good idea. [However,] I have a problem 
> with [the content of] this link:
> 
>  >  2. I SUGGEST THAT *EVERYONE* READ THIS:
>  >  http://article.gmane.org/gmane.comp.cms.opencms.devel/12565
> 
> A newcomer to OpenCms may not have been aware that 
> [modules written for] version 5 [of OpenCms are]
> fundamentally incompatible with version 6.  There is good [advice] in
> that posting, but it's also permanently embarrassing [to] the original
> poster[, Daniel Beinlich,] who, in my opinion, made a mistake 
> that many people could have
> made.

Joe,

	I agree with this opinion, and I would like to propose a solution. I 
propose that Alkacon post my "Troubleshooting list" (TL) to the OpenCms 
web site in a place where OpenCms users are likely to see it and use it. 
That way, we will not have to post links to Daniel Beinlich's email ever 
again and Daniel shall no longer suffer unnecessary embarrassment.

	I did not intend to embarrass Daniel. In fact, I was initially trying 
to help him. I apologize for any embarrassment that I may have caused him.

	BTW, I have revised my TL since January and have posted it at the 
bottom on this email. I have not been able to update it for version 6, 
however, because I was not able to install the beta versions of OpenCms 
6 on Debian Linux. I shall try to install version 6 again, but, when I 
do so, I shall use the final release of version 6.

> When I was evaluating CMS systems I looked at the associated email
> lists, the traffic, the quality of the replies and the general tone
> (friendly or cranky). Too many of those emails (no matter how
> justified) and I would have been dissuaded from evaluating any
> further.

<SNIP>

> On 7/5/05, Thomas Maerz <thomasmaerz at gmx.de> wrote:
> 
>>"Henry Chen" <henry.chen04 at gmail.com> writes:
>>
>>
>>>I got stuck with the following error when installing. Can anybody tell me
>>>the reason? Thank you very much.
>>
>>http://article.gmane.org/gmane.comp.cms.opencms.devel/12565
>>

>>BTW, does Paul want to be the head [of] the FAQ department?
>>
>>[I] Guess [that] we don't need a wiki but a weekly posted FAQ,
>>filled with links to posts on the mailing list?
>>
>>Maybe we could also crosspost some articles from
>>http://opencms-forum.de/ if SYNYX won't mind?
>>
>>Maybe gmane.org allows even superceding articles?

Thomas,

	I have thought about this matter a great deal already. At first, I 
thought that a web-based FAQ would be a good idea, and I investigated 
various means of erecting an FAQ for OpenCms. To this end, in December 
2004, I investigated "FAQ-ware" (FW), software that facilitates the 
erection of a web-based FAQ. I discovered several FW's that would 
probably suffice, but, now, am not certain that using them would be a 
good idea. Why? There are several reasons. The primary reason is that, 
after investigating various FW's, I discovered a second type of 
software, one that might serve my purposes far better than any FW. This 
second type of software facilitates establishing a link between a 
mailing list (such as this one) and "community-ware" (CW), which is 
software that facilitates the building of a web-based community. Here 
are some examples of popular CW's:

	(a) Slash, which is the software that runs Slashdot. See www.SlashCode.org.

	(b) phpBB, or "PHP Bulletin Board." Right now, this is probably the 
most popular CW in the world. Indeed, it is enormously popular.

	(c) Squishdot, a Slash clone that is written in Python (not Perl) and 
that runs in Zope, a Python application server.

	There are various names that could be used for this second type of 
software. These names include, for example, "mail2web" (mail-to-web), 
"mail2CW" (mail-to-CW) or "link-ware" (LW), software that builds a link 
between a mailing list (ML) and CW. I described one type of mail2CW in 
an email to the founder of my local Linux Users' Group, Greg Pryzby, a 
few weeks ago, in reply to Greg's request for help. Greg wanted to link 
an ML to a web site. You may read my email here:

	http://marc.theaimsgroup.com/?l=novalug&m=111851348313061&w=2

	I do not have the time to implement any mail2web software now. I shall 
not implement any mail2web as a means of linking this ML to a CW devoted 
to OpenCms -- not _now_. I may re-visit this idea later, however (when I 
have more time), and may implement one of the mail2web softwares that I 
have discovered.

------------- **** VERY IMPORTANT **** -----------------

	One of the assumptions behind my plan to use mail2web is that, once the 
content of this ML is in the RDBMS of a good CW, it will be fairly easy 
to build an FAQ from the contents of this ML. Indeed, IIRC, FAQ modules 
for certain CW (e.g., phpBB and Slash) already exist. I hope that I 
could use such a module to build an FAQ from the contents of this ML. 
First, however, I must decide how to get this ML's contents into the CW 
and then _maintain_ the link between the ML and the CW so that new 
emails are sent to the CW as well as to the ML. The mail2web software 
would handle that task. Or so I hope.
-----------------------------------------------------------

	Another assumption of my plans is that, after the ML's content is put 
into the CW's RDBMS, the ML will be easier to search than it is 
currently. Right now, it is difficult to search the archives of this ML. 
Why? I do not know. I simply know that I often cannot find what I want 
when searching the archives.

	If anyone has any suggestions on this matter, please let me know.

Sincerely,
Paul Bain

----------------


TROUBLESHOOTING OPENCMS -- version 2005-07-06
============================================================

Please do NOT post a request for help to this list until you have 
searched the list's archives. Furthermore, when requesting help, provide 
the information below. We are more likely to help you if we do not have 
to prod you for information!! Furthermore, we cannot help you if you do 
not provide enough information.

A. The most recent contents of these log files:
-------------------------------------------------------------------

	1. opencms.log

	2. catalina.out -- if you are using Tomcat

	3. The MySQL log file -- on Debian Linux, it is <hostname>.log The file 
"mysql.err" is _different_ from this file.

B. Your environment and configuration, in rough order of importance:
-----------------------------------------------------------------------------------

1. OpenCMS (OC) version number, for example (e.g.), ver. 5 or ver. 6. If 
version 6, state whether you are you using the final version, a beta 
version, or a release candidate.

2. Any OC modules that you have installed and their versions.

3. Servlet container and its version number, e.g., Tomcat (ver. 4.x or 
5.x), Jetty, or Resin. Remember that Resin has a history of not adhering 
to the servlet specification, causing problems for OC.

4. RDBMS and its version number, e.g., MySQL (ver 3.2x or 4.x), Oracle, 
or MS SQL Server.

5. JDK, including both of these items:

	(a) compiler (often called an "SDK," or "software development kit") and 
its version. Providers of SDK's include Sun Microsystems and Blackdown, 
whose SDK is popular on Linux. Examples of SDK's (from other providers) 
are IBM's Jikes and GNU's GCJ.
	
	(b) JVM (or the JRE, "Java Run-time Environment") and its version. 
Providers of JVM's include Sun and Blackdown. Examples of JVM's (from 
other providers) are Kaffe, SableVM, and GCJ (GCJ is not merely a Java 
compiler).

6. Operating system and its version. If using Linux, state the 
distribution and its version number, too. For example:

		a) Red Hat Enterprise Linux, ver. 4;
		
		b) SuSE Linux, ver. 9.2, or
		
		c) Debian Woody, Debian Sarge, or Debian Etch ("Testing"). If using 
Debian, state whether you are using "pinning" or otherwise mixing 
packages from two or more Debian distributions. Such mixing often causes 
problems on Debian, as when you are using packages from the unstable 
distribution (also called "sid") on the stable distribution, which is 
currently called "Sarge."

7. If you are using Linux, state whether you installed the software 
packages above using the package manager (PM) for your distribution. 
Examples of such PM's include these: RPM (Red Hat and SuSE), dpkg & 
APTitude (Debian Linux), emerge (Gentoo Linux), Stow, and "Apt for RPM," 
which allows you to use Debian's APT on a Linux distribution that is 
based on RPM.

If you are using Linux and did _not_ use a PM to install the relevant 
packages, did you install them manually, instead? For example, did you 
unpack a "tarball?" If so, was it a "source code" tarball or a binary 
tarball? If it was the former, how did you compile, link, and deploy the 
package? Please tell us.
	
8. The version of the JDBC driver is probably not necessary unless you 
have replaced the JDBC driver that the OC "set-up wizard" installs.

C. Configuration files
--------------------------------------

Sometimes, the contents of the primary OC configuration files are 
important, especially if you have edited them:
	
	1. opencms.properties
	2. registry.xml
	
I understand that OC ver. 6 has more configuration files than those that 
are listed above, but, at this moment, I cannot remember their names.