Hi Jon,
great that this has worked out so nicely for you! 8-)
On 06.02.2023 22:58, Sahananda Sahananda wrote:
Hi Gil, Rony,
Love the build tools. +1+1+1
Kudos go to Gil who has taken the responsibilty for the scripts, updates and extends them and
therefore earns the kudos! It is because of his work that it has become rather easy to load and to
setup the necessary packages.
(A couple of years ago the documentation project has almost stalled as it was almost impossible to
create the documentations anymore back then. The group of Gil, P.O. and myself have worked,
researched back then to finally make the documentation creation process work again, but this time on
all major operating system, i.e. Windows, MacOS and Linux.)
After removing some non-utf triple elipses (...) that should have been (. . .)
my changes now compile.
As well as the thousands of fo:region-after etc. warnings that have been the subject of a couple
of threads on this list I also see:
* WARNING: Font "Symbol,normal,700" not found. Substituting with
"Symbol,normal,400".
* WARNING: Font "ZapfDingbats,normal,700" not found. Substituting with
"ZapfDingbats,normal,400".
* WARNING: Font "Liberation Sans,normal,400" not found. Substituting with
"any,normal,400".
As long as the category is WARNING one can stay relaxed. :)
AFAIK the numbers with the font names indicate how bold the fonts to be loaded should be and in
these cases get replaced with normal fonts.
It indicates among other things that you have probably not yet installed the Liberation fonts into
your system (https://www.pcworld.com/article/394991/how-to-install-fonts-in-windows-10.html).
Not sure about bold versions of Symbol and ZapfDingbats as both fonts are
standard MS fonts.
* WARNING: span="inherit" on fo:block, but no explicit value found on the
parent FO.
* WARNING: Destination: Unresolved ID reference "book-oorexx-oodialog" found.
* WARNING: Destination: Unresolved ID reference "notices.title" found.
* WARNING: Destination: Unresolved ID reference "cplv10.title" found.
I can't find an fo:block or any of the unresolved ID references in the source
file I have edited
book-oorexx-oodialog is in book_info.xml
notices.title is in Notices.xml
cplv10.title is in CPLv1.0.xml
This usually means that the id is defined but not referenced.
Should these be a cause for concern do you think?
With the exception of the missing Liberation fonts, no, not really.
The Liberation font looks different to the "any" (default) font such that your produced PDF probably
does not look like the one created by the Jenkins.
HTH
---rony
On Mon, 6 Feb 2023 at 16:29, Sahananda Sahananda <sahana...@gmail.com> wrote:
Hi Rony, Gil,
I have the repository checked out and updated it just before working on the
docs.
Thanks for the build at home instructions. I will try to give it a go over
the next couple of
evenings.
Jon
On Mon, 6 Feb 2023 at 14:02, Gilbert Barmwater <gi...@bellsouth.net> wrote:
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
<http://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
<http://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
<http://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