I hope to reply specifically later today. GB
On 1/3/2023 10:02 AM, P.O. Jonsson wrote:
Dear Gil and Rony, I have responded to your comments below.
Hälsningar/Regards/Grüsse,
P.O. Jonsson
oor...@jonases.se
Am 03.01.2023 um 15:00 schrieb Gilbert Barmwater <gi...@bellsouth.net>:
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! :)
This needs more consideration but let me repeat the Mantra from Erich
(and I do believe he is right): EVERYTHING we build should be driven
from CMake, so the one place to keep such information must be in
CMakeLists.txt. This could result in a property file created from
CMake but the origin must be CMakeLists.txt
Rony: Let’s talk about this over a VICO or something, we are wasting
bandwidth here.
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.
In order for anyone interested to become aware of the tools,
documentation and the installers there is the „Files“ section on
Sourceforge
https://sourceforge.net/projects/oorexx/files/
This is NOT under version control and have, until now, been updated
sporadically manually, with the exception for the installers and the
documentation.
This is the ONLY place I expect a user to look for resources, if it is
not there it does not exist IMO.
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.
Agreed, but I was referring to a copy of the folder in the „Files“
section, not using SVN checkout
+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.
I agree that zip files are suboptimal for version control but your
tools will never be found buried deep in the SVN tree. Who will ever
find them it they are not on display in the „Files“ section? And if
you put your folder in that section people will give up trying to
download each item individually using the painful „click and wait 5
seconds and loose the focus on the page“.
What about a compromise: We try to keep everything under version
control unzipped and in separate folders (with meaningful names ;-) )
and then we have a script that will zip and upload everything to the
„Files" section? If agreed I would remove my zipped files and unzip
and commit them again as folders. Thereafter I would try to rewrite
the script that populates the „Files“ section. And do the same for the
build tools-
In any case I think it is of utmost importance that
(i) we showcase our tools on Sourceforge (not just bury them in SVN)
and that
(ii) any file handling that can be automated be automated.
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.
I would be in favour of leaving the publican files where they are in
the SVN tree and just not bring them to the „Files“ section.
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
-1 I agree with Gil here, changing anything would break also all my
tools so I would need to revisit them.
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
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
_______________________________________________
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
