On 7/2/2022 2:35 PM, Rony G. Flatscher wrote:
While probing downloading of the latest documentation files I noticed
that there are places that probably need some automated update in the
process of generating new versions of the documentation, e.g.:
rexxref.pdf has the following lines on the front page:
"ooRexx Documentation
/*5.0.0.r12338*/
Open Object Rexx
Reference
W. David Ashley
Rony G. Flatscher
Mark Hessling
Rick McGuire
Lee Peedin
Oliver Sims
Jon Wolfers"
rexxref.pdf - has the following version related lines on the
second page:
"ooRexx Documentation /*5.0.0.r12338*/ Open Object Rexx
Reference
/*Edition 0.2022.03.16*/"
It seems that at least the revision and the date needs to be updated
before producing the documentation.
This data is located in "rexxref/en-US/rexxref.ent", the current
entries are:
<!ENTITY VERSION "5.0.0.r12338">
<!ENTITY EDITION "0.2022.03.16">
These values should probably set to what "svn info" yields, i.e.
probably something like:
<!ENTITY VERSION "5.0.0.r12417">
<!ENTITY EDITION "2022.05.24">
From "oorexx/docs/trunc" issuing:
svn info --xml rexxref
yields (data to be parsed in bold):
<?xml version="1.0" encoding="UTF-8"?>
<info>
<entry
path="rexxref"
revision="12463"
kind="dir">
<url>svn+ssh://or...@svn.code.sf.net/p/oorexx/code-0/docs/trunk/rexxref</url>
<relative-url>^/docs/trunk/rexxref</relative-url>
<repository>
<root>svn+ssh://or...@svn.code.sf.net/p/oorexx/code-0</root>
<uuid>0b6cbdbe-3aab-466e-b73a-abd511dda0a2</uuid>
</repository>
<wc-info>
<wcroot-abspath>/cygdrive/f/work/svn/oorexx</wcroot-abspath>
<schedule>normal</schedule>
<depth>infinity</depth>
</wc-info>
*<commit****revision="12417">*
<author>orexx</author>
*<date>2022-05-24T14:40:07.488031Z</date>*
</commit>
</entry>
</info>
---
Maybe a suggestion would be to use the following values in the two
"rexxref/en-US/rexxref.ent" entries for better legibility:
<!ENTITY VERSION "5.0.0">
<!ENTITY EDITION "2022-05-24 (revision 12417)">
What do you think?
+1
Most developers don't know (or forget) that these entries in the entity
file need to be updated when changes are made to the document. Rexxref
seems to be the only book that has this pattern (it has been a long
while since I investigated this so I may not be remembering correctly).
If we desire to keep this, the document build process should probably
handle the updating.
---
The build process should be started after the changes got applied.
The same probably needs to be applied to all books.
---
Attention: there is one caveat here. If changing
"{book}/en-US/rexxref.ent" *no* commit should be done for that
particular book as a commit will increase the revision number and
change the date of the last change of the book! (It is a little bit
like a snake biting its own tail.)
A commit in a book should only be done if exisitng documentation of
that particular book got changed.
---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
