On 2/6/2023 6:50 AM, Rony G. Flatscher wrote:
Hi Jon,
On 05.02.2023 22:34, Sahananda Sahananda wrote:
I have updated and committed the xml file. I think that now an
automatic rebuild of the documentation will be triggered. Is that right?
Not sure. An automatic build gets triggered if code changes took place
IIRC. Maybe in that context the documentation may be recreated and
updated on the web site, just do not know.
If there are build errors how will I get to see them?
If you created the documentation yourself in the subdirectory
"log_files" (see below).
Creating the documentation for yourself is actually not really
difficult, here an attempt of a "how-to":
Probably the easiest (sic!) would be to check out the entire ooRexx
project via svn. Here the directions copied over:
-------- Forwarded Message --------
Subject: Getting oorexx docs, test, code from SourceForge to help
the oorexx project ... (Re: [rexxla-members] The external program
search order, source-relative paths, Call and Requires
Date: Fri, 20 Jan 2023 12:37:35 +0100
From: Rony Flatscher
To: rexxla-memb...@groups.io
... cut ...
... a coarse path:
* get svn for your operating system, if not already present
(e.g. Tortoise for Windows, on Unix the respective svn package)
* run:
o svn checkout https://svn.code.sf.net/p/oorexx/code-0/
oorexx-proj
* The above will create a directory "oorexx-proj" which contains
everything of the ooRexx project with the following important
directories:
o latest documentation: oorexx-proj/docs/trunk
o latest test framework: oorexx-proj/test/trunk
o latest code: oorexx-proj/main/trunk
Ad docs/trunk: go into the "tools" directory and study
"readme.txt". The build tools are either in bldoc_win (cmd
scripts) or bldoc_orx (Rexx scripts).
Basically all documentation is in DocBook XML and the xsl files
are used to transform it to pdf and html.
The XML text sources are in oorexx-proj/docs/trunk in
subdirectories named after the book, e.g. "rexxref/en-US"
(reference) or "rexxapi/en-US" (the API documentation). The cover
page and first pages are the same for all books and defined in
"oorexx/en-US".
The tools/bldoc* directories contain scripts that allow one to
create the books one by one. "setup" will try to download the
needed tools from the internet, "docprep" allows one to denote the
book to create and e.g. "doc2pdf" tries to create a pdf rendering
and places it, if successful into "pdf_files".
... cut ...
After checking out the ooRexx project as described above this would be
a fast-lane approach to create the documentation immediately:
* change into "oorexx-proj/docs/trunk/tools/bldoc_win" (I prefer
"bldoc_orx", but there is a little bug currently there)
Indeed there is but I have located the issue and have designed a fix
which I am in the midst of developing and testing.
o you may want to skim over "read1st.txt"
* run "setup.rex" (will download all software needed to create the docs)
* then each time you want to create a book (bldoc_win will use
environment variables if not mistaken, so the following steps
might have to be repeated for each new session):
o run "docpath.cmd %cd%\..\..\orexx-proj\docs\trunk" (or define
an absolute path): this is the location where book directories
are rooted
o run "docprep.cmd oodialog" (this defines the book-directory
looked up in docpath)
o run "doc2pdf.cmd": this will run in sequence
+ "doc2fo.cmd": creates the fo-file "oodialog.fo" in the
"fo_files" directory placing any log output
("oodialog.log") into "log_files"
+ "fo2pdf.cmd": creates the pdf-file "oodialog.pdf" in the
"pdf_files" directory from the fo-file "fo_files\oodialog.fo"
So when everything went fine you would have the pdf file in the
"pdf_files" subdirectory. If not, then there was probably an error
creating the fo-file "oodailog.fo" which would be described in
"log_files\oodialog.log".
---
Please note: regularly do a "svn update" to get the latest changes
from SourceForge, also it may be the case that each time you change
something in the xml files that you need to run "docprep.cmd oodialog"
to get the working directory updated (this is the case currently when
using "bldoc_orx").
Just an aside here - bldoc_win uses the working copy so it will pick up
any changes to the xml files but because it uses environment variables
to "remember" things like the document name, opening a new cmd prompt
will require running all of the commands from the "top". And note that
doc2pdf <book name> will run docprep under the covers so it need not be
a separate step.
HTH
---rony
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
