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

Reply via email to