[Oorexx-devel] Publican Sandbox

[David A. <w.d...@gm...>]

All -

I have commited my Publican sandbox to SVN. You can check it out at
http:..oorexx.svn.sourceforge.net/svnroot/oorexx/sandbox/david/publican.

Here are some notes about Publican and the sandbox source.

1. Publican uses a "brand" concept to give a project a customized look
and feel for their documentation. Our brand is contained in the oorexx
subdirectory. This brand must be built and then installed on the build
machine. There is a Makefile in the oorexx directory and all you need to
do is run "make brand" and then run "make install". The "make install"
assumes you have sudo authority to write to the target install directory
(/usr/share/publican on Linux systems).

2. The rxsock subdirectory contains everything needed for the rxsock
documentation. It was built using the "publican create" command and then
customized. When ou create a new document you really only need to copy
the directory structure of another document and then customize it.

3. To build rxsock just run "make pdf" or "make html" from the rxsock
directory (rxsock has to be your current directory). This will create a
new directory called tmp. You will find your output in either
tmp/en-US/pdf or tmp/en-US/html. If files can not be found then you
probably forgot to install the brand. See step 2.

4. A documentation build causes the brand files and the document files
to be merged in the document's tmp directory. First the brand files are
copied and then the document files are copied to this location. This
allows the document files to override the brand files so that a document
can vary from the brand if necessary.

5. There are some special files that need attention for each release
cycle. The one you have to touch is the entities file. For rxsock this
is located in rxsock/en-US/rxsock.ent. Every document will have one of
these entities file with its own name but always with the .ent
extension. The entities file has a version variable that needs to be
updated for each release of the documentation.

I know I have probably forgotten some things but this should get you
started. The main Publican web page is at
https://fedorahosted.org/publican/. There is a link to the user's guide
on that page. I was able to figure everything out from that guide.

Do not hesitate to drop me an email if you run into problems.

David Ashley