On Sat, Feb 29, 2020 at 11:13 AM Gil Barmwater <gbarmwa...@alum.rpi.edu> wrote:
> Hi Rony, > > First of all, thanks for the kind comments! And I really appreciate the > feedback and suggestions as well. > > Now to the specific items in the order you listed them. The issue with the > "missing folders" is one I ran into as well. It comes from the fact that I > was not able to include empty folders in the zip file and so had to create > them the first time they were needed. I chose to do that in the docprep > step when all the other "housekeeping" is done. Since you (and I) had > already run docprep with the previous version, the "housekeeping section" > had already run so the folders were not created. This should only be a > problem for you, P.O. and I (or anyone else with v1) that had run version 1 > of the package.?? > > I will look into a change to only issue the "PDF created" if the file > actually exists as I don't know that the FOP .bat file gives any kind of > "errorlevel" that I could test. This approach could give a false > "success"?? message if there was a previous file but the step had failed. > > The svn revision on the cover page of the rexxref is "hard coded"; i.e. a > DTD entity supplies this value which is set in the file rexxref.ent. So a > manual update of that file is required which doesn't always happen when > other parts of the book are modified. > > Assuming ooRexx is installed is pretty safe but it could be verified using > the "where" command. The difficulty in using Rexx scripts however comes > from my decision to use environment variables to hold e.g. docpath and > whichdoc. I also wanted the various steps to be able to be run > independently so those variables need to "persist" between steps. Using > simple "set" commands in a Rexx script will not accomplish that as they "go > away" when the script ends. I believe one could use the registry class(?) > to make them "permanent" but that then precludes a *ix solution. > > I have not done anything with HTML as I am not sure what our Publican > process does to build them. This is surely another work item if we are to > completely remove our dependency on Publican. > Gil, I believe publican generated them directly using a style sheet. This can also be done using xsltproc: https://codeghar.wordpress.com/2012/02/07/generate-html-and-pdf-from-docbook-in-debian/ > The package does not make use of either the makefile or publican.cfg file > that appear in the book directories. The only Publican-related files that > the package uses are the two stylesheets - pdf.xsl and defaults.xsl which > are in the package itself. BTW, the sources.txt file in the package > documents all the pieces and from where they are derived. > > Thanks again for the feedback and suggestions. They are always welcome! > > Gil B. > On 2/29/2020 10:11 AM, Rony G. Flatscher wrote: > > Dear Gil: > On 28.02.2020 19:12, Gil Barmwater wrote: > > I have just uploaded version 1.1 of the package to my Dropbox. In addition > to the changes I mentioned earlier (see below), I have modified the > location of the output files. There are now only three folders - fo_files, > log_files, and PDF_files - instead of a folder per document. The link I > supplied earlier will still work but here > <https://www.dropbox.com/s/s5d9mwx63xru1tk/orxbldoc.zip?dl=0> it is again > so you don't need to hunt for it. Again, feedback is welcome! > > Used your new version 1.1, but got into (small) troubles using "doc2pdf > rexxref": > > G:\oorexx.tmp\gilDocs\orxbldoc-1.1>doc2pdf rexxref > F:\work\svn\oorexx\docs\trunk\rexxref\en-US\Common_Content already exists. > 15:40:34 - Transforming > F:\work\svn\oorexx\docs\trunk\rexxref\en-US\rexxref.xml to fo_files\rexxref.fo > This may take more than 5 minutes! > Making portrait pages on A4 paper (210mmx297mm) > 15:49:19 - Transformation complete > 15:49:19 - Creating PDF_files\rexxref.pdf from fo_files\rexxref.fo using > Apache FOP > The system cannot find the path specified. > 15:49:19 - PDF created > > Remarks: > > - Please note that in my case the doc2fo step takes almost 9 minutes, > hence I would suggest to give the warning 10 minutes instead of the current > 5 minutes (otherwise users may fear that the process hung up if one has to > wait more than 5 minutes). > > - the fo2pdf step was not carried out, because of missing directories > ("log_files", "PDF_files"), here the double-check: > > G:\oorexx.tmp\gilDocs\orxbldoc-1.1>fo2pdf > 15:51:35 - Creating PDF_files\rexxref.pdf from fo_files\rexxref.fo using > Apache FOP > The system cannot find the path specified. > 15:51:35 - PDF created > > > - after creating the two missing subdirectories "log_files" and > "PDF_files" manually the process concluded successfully in the fo2pdf step: > > G:\oorexx.tmp\gilDocs\orxbldoc-1.1>md log_files PDF_files > > G:\oorexx.tmp\gilDocs\orxbldoc-1.1>fo2pdf > 15:52:21 - Creating PDF_files\rexxref.pdf from fo_files\rexxref.fo using > Apache FOP > 15:52:47 - PDF created > > Maybe the success message "PDF created" should only be given if the fo2pdf > step was carried out? > > One more observation: I updated the documentation via svn to revision > 11985, yet the book reads 5.0.0.r11982 on the title page (this may stem > from my prior tests a few days ago). Doing a "svnversion %docpath%" yields > currently revision 11985. > > --- > > Overall, *extremely impressed* how easy and straight forward it has become > to create rexxref.pdf, something I (and many others) simply would not have > been able to do before your hard work and making the toolchain and the > scripts available to us! Kudos!! > > The time, work and efforts you have invested here is really great for the > entire community! > > Ad oodguide errors: I have added some code to create the files that book > is trying to include but be aware that they are in the PARENT folder of the > folder specified for docpath. This will cause a problem if you should have > that folder on say a portable drive but not under another directory. E.g > using d:\rexx\theDocs for docpath would be OK but d:\theDocs would fail. I > would prefer to have those files be created down one level but that will > need a change to the source for the oodguide book. If that change gets made > I will update the package. > > Ad the errors (32) in the winextensions book: I have not had a chance to > investigate why they are being generated but they seem to correspond to the > 32 occurrences of (???) in the PDF file on SVN. > > Ad syntax highlighting of C++ code: this appears to be a built-in feature > of Publican which is not available for xsltproc. More investigation is > needed to determine what to do about it. > > While I have accomplished what I intended - allowing anyone to build the > ooRexx documentation on Windows 10 - there is more work to be done going > forward. I would be happy to provide assistance to anyone wishing to port > the package to *ix. This would involve using the *ix versions of the > xsltproc tools and writing shell scripts to replace the *.cmd files. > > +1 > > Just an idea/a question: how about assuming that ooRexx 5.0 is installed > and because of that writing a small Rexx script that would replace the > shell scripts for all operating systems (differences among the operating > systems could be taken care of in such a Rexx script)? E.g. this would > allow .datetime to be used for measuring the different steps (the different > commands) > > And we should look into moving from Docbook 4.5 to 5.0, a non-trivial task > from what I have determined. Investigating other tools to do the > transformation could give us the ability to syntax-highlight not only the > C++ code but also the ooRexx. > > May I just ask a question ad html-production: have you been able to look > into that corner? P.O. reported that with his Publican, Windows 7 confined > version the html text would not look good. It would be great to have all of > ooRexx' documentation on the web, such that people can quickly find it by > searching the Internet (very much like finding the documentation e.g. for > any Java class). > > Another question maybe: I notice that in the book directories there are > two Publican related files: Makefile and publican.cfg. Are they needed (or > any of the Publican related files) for your solution? > > Best regards > > ---rony > > > > > _______________________________________________ > Oorexx-devel mailing > listOorexx-devel@lists.sourceforge.nethttps://lists.sourceforge.net/lists/listinfo/oorexx-devel > > -- > Gil Barmwater > > _______________________________________________ > 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
