I was going to reply to the OP that I saw last night but then I saw this
reply from Rony so I have added my comments below.
On 1/3/2023 5:44 AM, Rony G. Flatscher wrote:
Thank you (and also Gil) for all of your efforts!
On 03.01.2023 00:18, ooRexx wrote:
My attempt to always have the documentation built before windows and
macOS build backfired. "monitoring" the documentation build resulted
in Windows and macOS building as soon as there was a change to the
documentation, also when there is no change to the source codebase.
So I have reverted that change.
The other way around, to have Windows and/or initiating a
documentation build for every source code change might work (the
documentation build will exit silently if there are no changes) but I
think it will eventually lead to problems. In the normal situation
the documentation will be fairly stable so ready to be picked up. For
a release scenario we might need to be a bit more disciplined and let
a couple of hours pass between documentation changes and final build.
I hope this is acceptable.
One possibility is to use "tools/svnListRevisions.rex" exactly as
"tools/updateEntityValues.rex" to determine if a book's part got
updated (ignoring the ${book}/en-US/${book}.ent and
${book}/en-US/Author_Group.xml files) and only recreate and upload
that book if so.
I have amended the script building and uploading the documentation to
accept download and upload paths, so that is can be driven by cMake
when we know how to use that as variables.
One possibility would be to place an ooRexx property text file
containing current build definitions at a location that can be read
from all Jenkins-clients. If it does not exist a fallback would be to
use trunk only.
Such a textfile could look like:
main=5.1.0beta
docs=5.0.0 5.1.0beta
test=5.1.0beta
with the meaning create ooRexx 5.1.0beta (main-entry), the
documenation for 5.0.0 and 5.1.0beta (docs-entry), run the tests for
5.1.0beta from 5.1.0beta.
Or something like that.
The location could be on SourceForge and a backup location accessible
from each Jenkins client (if that can be configured).
This is just one idea meant for further brainstorming! :)
Along the same lines I have written yet a rexx script that checks if
any changes have been made to docs-bildutils, and if so, update the
"Files" section of sourceforge so that we now have an automated way
to update also docs-bildutils
+1
So my first question is what is the purpose of the docs-bildutils
folder? Are there files in it that are unique and not located elsewhere
in SVN? I am having difficulty in reconciling what is there vs. what is
in the docs\trunk\tools folder.
The script is launched from the Project ooRexx-docs-bildutils-check
and hopefully we can provide the necessary input to the script from
CMakeLists.txt in a later stage.
I did only consider files so far, I have a question on the folders
*rexxpg bldoc_win bldoc_orx*
*rexxpg* only contain two files so it is doable to download them
using the enerving "wait five seconds" downloading function but
for*bldoc_win* and *bldoc_orx* (what is the difference)
AFAIK "bldoc_orx" is the newer version using Rexx scripts instead of
the shell scripts in "bldoc_win", thereby allowing it to be used on
Unix systems as well. However, Gil knows more as he is the author! :)
Rony is correct. The latter was a rewrite from the Windows batch files
and environment variables to ooRexx scripts and a properties file. It
also uses a "cleaner" method to resolve the 'Common_Content' used by
Publican. The intent when it was written was that it would run on both
Windows and *nix platforms but, to my knowledge, it has never been
tested on *nix.
there are some 20 separate files and folders, making downloading it a
nightmare. I suggest to put everything together as a zipfile, in that
way it is a one-click to get it.
The files under version control should remain as it makes it easy to
directly work with them.
+1
I, personally, do not think zip files belong in a version control
system. Here is how I see someone using the bldoc_xxx tools: checkout
the docs\trunk folder using SVN, copy the bldoc_xxx folder from \tools
to a folder that will be used for building the document(s), get the "off
the shelf" tools needed (on Windows, run setup.rex), run docpath to
point to the path for the "checked out" documents, etc.
OTOH the files put into the unversioned files area of Sourceforge can
be in the zipped form, as it is really easier for downloading.
The folder publican_obsolete is just that, obsolete, so I do not
expect anyone to use it but it is kept for backwards compatibility.
The question is whether anyone is able and wants to re-create older
documentation. We could remove "publican_obsolete" from trunk as it
still would be present in the older releases branches.
+1
AFAIK, it is still possible at this point to run Publican as we have not
"burned the bridge" that would prevent that toolset from running.
Having the old tools in the SVN repository should be adequate to
preserve that capability.
While being there we should also consider to rename the directory
"docs/trunk/oorexx" to "docs/trunk/Common_Content" as it gets used for
all books. After doing so, we should also consider to change all the
xml-files that refer to "Common_Content" to refer relatively to it
which would allow us to forgo copying "oorexx\en-US" into all
"books\en-US\Common_Content".
-1
This would "break" the Publican tools and, IMHO, does not provide any
real benefit as the "copying" step is only done during the "docprep"
stage, once per document and, as the file is very small, does not impose
a performance hit.
In the coming days I will go through the list and see what is missing
on my part and delete/summarize those sections.
+1
---rony
_______________________________________________
Oorexx-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
_______________________________________________
Oorexx-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
