Dear Gil, Having slept on it I think you are right, anyone interested in building the documentation must check out the entire /docs/trunk and so have the tools folder already.
Would it be acceptable to all if I empty the oorexx-docs-bildutils folder in the „Files“ section and keep only the readme for /docs/trunk/tools there? In that way it would be immediately clear (the readme will display) what it is and how to use it. I will keep a script on Jenkins monitoring the /docs/trunk/tools/readme.txt so that it is always updated automatically. I will remove my zipped files today and check them back in as folders. Shall I do the same with the LiberationFonts.zip? Hälsningar/Regards/Grüsse, P.O. Jonsson oor...@jonases.se > Am 03.01.2023 um 23:01 schrieb Gilbert Barmwater <gi...@bellsouth.net>: > > See below; trimmed some of the post... > > On 1/3/2023 11:36 AM, Gilbert Barmwater wrote: >> 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 <mailto:oor...@jonases.se> >>> >>> >>>> Am 03.01.2023 um 15:00 schrieb Gilbert Barmwater <gi...@bellsouth.net >>>> <mailto: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: > 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. > Well, it appears we have different views on this topic :-) Let me start with > my view of the user who is interested in building the documents, assuming > there are any others beside myself, Rony, you and Erich. If documents are > available at the latest level in both PDF and HTML, who would want to build > them from source? Probably someone who is interested in adding to or > changing one (or more) of them. If so, they are NOT going to "download" the > source file(s), one by one. They are going to do an "svn checkout" of > docs/trunk. (Note that attempting to "checkout" just a single document will > not allow it to be built as all the documents rely on "Common_Content".) If > they do that successfully, they will also have the /tools folder as well. So > I would not expect that user to be looking in "files" for anything as they > are, to me, "output" like various builds or pre-built documents. > > Now I have no objection to having "how to" files in that section that would > explain the steps necessary to get started with building a private version of > the interpreter or a modified version of a document. For document-building, > it would indicate 1) the need to checkout ALL of docs/trunk, and 2) direct > the user to the appropriate read1st file in the /tools folder in the working > copy for the succeeding steps. > > I really disagree with having things in multiple places as it can only lead > to failures to keep everything in sync when changes are made. To me its like > hard-coding values in a program which inevitably leads to a missed update and > very hard-to-find errors. > >>> >>>>>> 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 > See my comment above about having multiple copies of things. >>>> +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“. > See comments above. >>> >>> 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. > Again, see previous comments. Casual users are not interested in the "gory > details" of the tools used to create our builds or our documents and serious > users wishing to edit a document and view the results will not have a problem > with the tools being in SVN and available as soon as they "checkout" the > document source. >>>>> OTOH the files put into the unversioned files area of Sourceforge can be >>>>> in the zipped form, as it is really easier for downloading. >>>>> > Already addressed. >>>>> >>>>> >> >> >> >> _______________________________________________ >> 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
