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/
<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
>> <mailto:Oorexx-devel@lists.sourceforge.net>
>> https://lists.sourceforge.net/lists/listinfo/oorexx-devel
>> <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
