Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[Jon Wolfers]

I would like to add my voice to the chorus of approval.  Great work Gil!

Jon

On Mon, 16 Dec 2019 at 19:13, Rony G. Flatscher 
wrote:

> Gil:
>
> that is really a *great* achievement, thank you very much for all of your
> efforts! This is really great for the ooRexx project!
>
> Whenever you want "nit-picking" feedback, please let us know, the overall
> documentation is looking very professional and attractive already!
>
> Also, whenever you are ready to share how you did this and what we need to
> do to do that also, I will try to create the documenation as well. This
> will allow us to try to help with the documentation as we would become able
> to test whether our changes would lead to successful creation and
> attractive documentation, relieving Rick and Erich in that corner a bit!
>
> Best regards,
>
> ---rony
>
>
> On 16.12.2019 16:40, Gil Barmwater wrote:
>
> As a result of Jon's request, I have now done the RxMath PDF as well.
> Doing another document helped me formalize the process so that I can
> automate it and it identified another small issue which I thought had been
> corrected. You can download the PDF here
>  for
> comparison to the rxmath.pdf that is in the docs folder of your 5.0.0
> ooRexx installation or the Files section on SourceForge. The differences I
> found are 1) the Copyright dates on the second page now show -2019, and 2)
> the flow of the text in some sections is slightly different due to extra
> blank lines in the code examples. This issue was identified and fixed by
> Erich with a preprocess Rexx program when building our docs using Publican
> so it can be adapted to my process if I am unable to find the cause and
> change it. His program also needed to fix blank lines in the Index area but
> that looked OK to me in my build. Comments welcome.
>
> Gil
>
>
> ___
> 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

Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[Rony G. Flatscher]

Gil:

that is really a *great* achievement, thank you very much for all of your 
efforts! This is really
great for the ooRexx project!

Whenever you want "nit-picking" feedback, please let us know, the overall 
documentation is looking
very professional and attractive already!

Also, whenever you are ready to share how you did this and what we need to do 
to do that also, I
will try to create the documenation as well. This will allow us to try to help 
with the
documentation as we would become able to test whether our changes would lead to 
successful creation
and attractive documentation, relieving Rick and Erich in that corner a bit!

Best regards,

---rony


On 16.12.2019 16:40, Gil Barmwater wrote:
>
> As a result of Jon's request, I have now done the RxMath PDF as well. Doing 
> another document
> helped me formalize the process so that I can automate it and it identified 
> another small issue
> which I thought had been corrected. You can download the PDF here
>  for comparison to 
> the rxmath.pdf that
> is in the docs folder of your 5.0.0 ooRexx installation or the Files section 
> on SourceForge. The
> differences I found are 1) the Copyright dates on the second page now show 
> -2019, and 2) the flow
> of the text in some sections is slightly different due to extra blank lines 
> in the code examples.
> This issue was identified and fixed by Erich with a preprocess Rexx program 
> when building our docs
> using Publican so it can be adapted to my process if I am unable to find the 
> cause and change it.
> His program also needed to fix blank lines in the Index area but that looked 
> OK to me in my build.
> Comments welcome.
>
> Gil
>

___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[Gil Barmwater]

René,

The process I'm using is for Windows but I believe it should be 
adaptable to Linux as well. That is to say there is a version of the 
transform tool set for Linux and Fop is just Java. My plan was to get 
the package together and then ask P.O. to try it out (heads up P.O.!). 
If we get that working, I can make the package available to everyone.


Gil

On 12/16/2019 12:50 PM, René Jansen wrote:

Hi Gil,

that looks great! I hope we can build the docs on Jenkins so that will 
be available when we need it. Probably P.O. can help us with this. Do 
you only build doc on Windows or also Linux?


best regards,

René

On 16 Dec 2019, at 11:40, Gil Barmwater > wrote:


As a result of Jon's request, I have now done the RxMath PDF as well. 
Doing another document helped me formalize the process so that I can 
automate it and it identified another small issue which I thought had 
been corrected. You can download the PDF here 
 for 
comparison to the rxmath.pdf that is in the docs folder of your 5.0.0 
ooRexx installation or the Files section on SourceForge. The 
differences I found are 1) the Copyright dates on the second page now 
show -2019, and 2) the flow of the text in some sections is slightly 
different due to extra blank lines in the code examples. This issue 
was identified and fixed by Erich with a preprocess Rexx program when 
building our docs using Publican so it can be adapted to my process 
if I am unable to find the cause and change it. His program also 
needed to fix blank lines in the Index area but that looked OK to me 
in my build. Comments welcome.


Gil



Jon,

Yes, of course you are right, I need to do a more complex document to 
see if there are other issues in addition to those I've identified so 
far. Stay tuned...


On 12/11/2019 2:19 PM, Jon Wolfers wrote:

Hi Gil,

Looks good to me, but I'm not sure what to look for.  Any chance of 
a doc with railroad diagrams?


Jon

On Wed, 11 Dec 2019, 19:00 Gil Barmwater, > wrote:


Thanks for the feedback Rony. Anyone else have any comments? If
not, I will start posting comments on the issues I have found
shortly. My goal is to develop a package containing the tools
that anyone can download and install that will allow them to
build our docs on Windows 10 from a fresh checkout from
SourceForge with minimal changes to those files.

On 12/10/2019 12:45 PM, Rony G. Flatscher wrote:

Wow, that is *fantastic* news!! Also, looking at your
readme.pdf it looks terrific IMHO!

Very curious what you have come up with to be able to generate
the ooRexx 5.0 documentation yourself� (and also about the
questions that you will pose in order to learn about the
current problems from them and become able to build the ooRexx
documentation in the near future and in a future-safe way)!

Kudos!

---rony

On 10.12.2019 18:17, Gil Barmwater wrote:


I know it has been over a month since I posted the note below
but I now have a lot of progress to report! I have obtained
the tools needed to build our docs - they are open source and
seem well supported - and have successfully built one document
using them on Windows 10. There are no dependencies on
Publican other than three files I chose to retain to simplify
the transition. Installing and using the tools was pretty
painless but in doing so I uncovered a number of issues with
our documents, most of which are due to our use of Publican
and what it does "under the covers". Rather than turning this
email into a "book", I will send separate notes on each issue
and the changes needed in order to use the new tools. In the
meantime, here
 is
a link to a file in my Dropbox for the readme.pdf that I
built. Once the link opens in your browser, you can click on
the ... icon on the right which will open a menu that will
allow you to download the file. If you then compare it to the
readme.pdf that is in the docs folder of your 5.0.0 ooRexx
installation or the Files section on SourceForge, you will see
it is (almost) identical. The differences are 1) the text has
been updated in section 2.2, 2) the Copyright dates on the
first page now show -2019, 3) the flow of the text in some
sections is slightly different, in some cases causing text to
flow to the next page, and 4) the Table of Contents has more
levels listed. I did not feel that either of the last two
items were worth pursuing. Let me know what you think after
you've had a look.

Gil B.

Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[taf]

Wow!  This looks absolutely great.  Wonderful work Gil, thanks.

On 2019-12-16 07:40, Gil Barmwater wrote:


As a result of Jon's request, I have now done the RxMath PDF as well. 
Doing another document helped me formalize the process so that I can 
automate it and it identified another small issue which I thought had 
been corrected. You can download the PDF here 
 for 
comparison to the rxmath.pdf that is in the docs folder of your 5.0.0 
ooRexx installation or the Files section on SourceForge. The 
differences I found are 1) the Copyright dates on the second page now 
show -2019, and 2) the flow of the text in some sections is slightly 
different due to extra blank lines in the code examples. This issue 
was identified and fixed by Erich with a preprocess Rexx program when 
building our docs using Publican so it can be adapted to my process if 
I am unable to find the cause and change it. His program also needed 
to fix blank lines in the Index area but that looked OK to me in my 
build. Comments welcome.


Gil



Jon,

Yes, of course you are right, I need to do a more complex document to 
see if there are other issues in addition to those I've identified so 
far. Stay tuned...


On 12/11/2019 2:19 PM, Jon Wolfers wrote:

Hi Gil,

Looks good to me, but I'm not sure what to look for.  Any chance of a 
doc with railroad diagrams?


Jon

On Wed, 11 Dec 2019, 19:00 Gil Barmwater, > wrote:


Thanks for the feedback Rony. Anyone else have any comments? If
not, I will start posting comments on the issues I have found
shortly. My goal is to develop a package containing the tools
that anyone can download and install that will allow them to
build our docs on Windows 10 from a fresh checkout from
SourceForge with minimal changes to those files.

On 12/10/2019 12:45 PM, Rony G. Flatscher wrote:

Wow, that is *fantastic* news!! Also, looking at your readme.pdf
it looks terrific IMHO!

Very curious what you have come up with to be able to generate
the ooRexx 5.0 documentation yourself� (and also about the
questions that you will pose in order to learn about the current
problems from them and become able to build the ooRexx
documentation in the near future and in a future-safe way)!

Kudos!

---rony

On 10.12.2019 18:17, Gil Barmwater wrote:


I know it has been over a month since I posted the note below
but I now have a lot of progress to report! I have obtained the
tools needed to build our docs - they are open source and seem
well supported - and have successfully built one document using
them on Windows 10. There are no dependencies on Publican other
than three files I chose to retain to simplify the transition.
Installing and using the tools was pretty painless but in doing
so I uncovered a number of issues with our documents, most of
which are due to our use of Publican and what it does "under
the covers". Rather than turning this email into a "book", I
will send separate notes on each issue and the changes needed
in order to use the new tools. In the meantime, here
 is
a link to a file in my Dropbox for the readme.pdf that I built.
Once the link opens in your browser, you can click on the ...
icon on the right which will open a menu that will allow you to
download the file. If you then compare it to the readme.pdf
that is in the docs folder of your 5.0.0 ooRexx installation or
the Files section on SourceForge, you will see it is (almost)
identical. The differences are 1) the text has been updated in
section 2.2, 2) the Copyright dates on the first page now show
-2019, 3) the flow of the text in some sections is slightly
different, in some cases causing text to flow to the next page,
and 4) the Table of Contents has more levels listed. I did not
feel that either of the last two items were worth pursuing. Let
me know what you think after you've had a look.

Gil B.


--
Just so everyone doesn't think I've abandoned this effort, I am
pursuing another approach to building the docs. You can expect
an update when I've made some more progress.


On 11/4/2019 4:16 PM, Gil Barmwater wrote:

?I will go back to docbook.org  and do
some more reading before proceeding any further with Pandoc.

-- 
Gil Barmwater




___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net  

Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[René Jansen]

Hi Gil,

that looks great! I hope we can build the docs on Jenkins so that will be 
available when we need it. Probably P.O. can help us with this. Do you only 
build doc on Windows or also Linux?

best regards,

René

> On 16 Dec 2019, at 11:40, Gil Barmwater  wrote:
> 
> As a result of Jon's request, I have now done the RxMath PDF as well. Doing 
> another document helped me formalize the process so that I can automate it 
> and it identified another small issue which I thought had been corrected. You 
> can download the PDF here 
>  for comparison to 
> the rxmath.pdf that is in the docs folder of your 5.0.0 ooRexx installation 
> or the Files section on SourceForge. The differences I found are 1) the 
> Copyright dates on the second page now show -2019, and 2) the flow of the 
> text in some sections is slightly different due to extra blank lines in the 
> code examples. This issue was identified and fixed by Erich with a preprocess 
> Rexx program when building our docs using Publican so it can be adapted to my 
> process if I am unable to find the cause and change it. His program also 
> needed to fix blank lines in the Index area but that looked OK to me in my 
> build. Comments welcome.
> 
> Gil
> 
> 
> 
> Jon,
> 
> Yes, of course you are right, I need to do a more complex document to see if 
> there are other issues in addition to those I've identified so far. Stay 
> tuned...
> 
> On 12/11/2019 2:19 PM, Jon Wolfers wrote:
>> Hi Gil,
>> 
>> Looks good to me, but I'm not sure what to look for.  Any chance of a doc 
>> with railroad diagrams?
>> 
>> Jon 
>> 
>> On Wed, 11 Dec 2019, 19:00 Gil Barmwater, > > wrote:
>> Thanks for the feedback Rony. Anyone else have any comments? If not, I will 
>> start posting comments on the issues I have found shortly. My goal is to 
>> develop a package containing the tools that anyone can download and install 
>> that will allow them to build our docs on Windows 10 from a fresh checkout 
>> from SourceForge with minimal changes to those files.
>> 
>> On 12/10/2019 12:45 PM, Rony G. Flatscher wrote:
>>> Wow, that is *fantastic* news!! Also, looking at your readme.pdf it looks 
>>> terrific IMHO!
>>> 
>>> Very curious what you have come up with to be able to generate the ooRexx 
>>> 5.0 documentation yourself� (and also about the questions that you will 
>>> pose in order to learn about the current problems from them and become able 
>>> to build the ooRexx documentation in the near future and in a future-safe 
>>> way)!
>>> 
>>> Kudos!
>>> 
>>> ---rony
>>> 
>>> On 10.12.2019 18:17, Gil Barmwater wrote:
 I know it has been over a month since I posted the note below but I now 
 have a lot of progress to report! I have obtained the tools needed to 
 build our docs - they are open source and seem well supported - and have 
 successfully built one document using them on Windows 10. There are no 
 dependencies on Publican other than three files I chose to retain to 
 simplify the transition. Installing and using the tools was pretty 
 painless but in doing so I uncovered a number of issues with our 
 documents, most of which are due to our use of Publican and what it does 
 "under the   covers". Rather than turning this email into 
 a "book", I will send separate notes on each issue and the changes needed 
 in order to use the new tools. In the meantime, here 
  is a link to a 
 file in my Dropbox for the readme.pdf that I built. Once the link opens in 
 your browser, you can click on the ... icon on the right which will open a 
 menu that will allow you to download the file. If you then compare it to 
 the readme.pdf that is in the docs folder of your 5.0.0 ooRexx 
 installation or the Files section on SourceForge, you will see it is 
 (almost) identical. The differences are 1) the text has been updated in 
 section 2.2, 2) the Copyright dates on the first page now show -2019, 3) 
 the flow of the text in some sections is slightly different, in some cases 
 causing text to flow to the next page, and 4) the Table of Contents has 
 more levels listed. I did not feel that either of the last two items were 
 worth pursuing. Let me know what you think after you've had a look.
 
 Gil B.
 
 --
 Just so everyone doesn't think I've abandoned this effort, I am pursuing 
 another approach to building the docs. You can expect an update when I've 
 made some more progress.
 
 
 On 1

Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[Mike Cowlishaw]

 

As a result of Jon's request, I have now done the RxMath PDF as well. Doing
another document helped me formalize the process so that I can automate it
and it identified another small issue which I thought had been corrected.
You can download the PDF here
  for comparison
to the rxmath.pdf that is in the docs folder of your 5.0.0 ooRexx
installation or the Files section on SourceForge. The differences I found
are 1) the Copyright dates on the second page now show -2019, and 2) the
flow of the text in some sections is slightly different due to extra blank
lines in the code examples. This issue was identified and fixed by Erich
with a preprocess Rexx program when building our docs using Publican so it
can be adapted to my process if I am unable to find the cause and change it.
His program also needed to fix blank lines in the Index area but that looked
OK to me in my build.  

 Comments welcome.
 

 Looks excellent!!!

___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Questions ad generating the documentation (publican, pandoc)

[Gil Barmwater]

As a result of Jon's request, I have now done the RxMath PDF as well. 
Doing another document helped me formalize the process so that I can 
automate it and it identified another small issue which I thought had 
been corrected. You can download the PDF here 
 for 
comparison to the rxmath.pdf that is in the docs folder of your 5.0.0 
ooRexx installation or the Files section on SourceForge. The differences 
I found are 1) the Copyright dates on the second page now show -2019, 
and 2) the flow of the text in some sections is slightly different due 
to extra blank lines in the code examples. This issue was identified and 
fixed by Erich with a preprocess Rexx program when building our docs 
using Publican so it can be adapted to my process if I am unable to find 
the cause and change it. His program also needed to fix blank lines in 
the Index area but that looked OK to me in my build. Comments welcome.


Gil



Jon,

Yes, of course you are right, I need to do a more complex document to 
see if there are other issues in addition to those I've identified so 
far. Stay tuned...


On 12/11/2019 2:19 PM, Jon Wolfers wrote:

Hi Gil,

Looks good to me, but I'm not sure what to look for.  Any chance of a 
doc with railroad diagrams?


Jon

On Wed, 11 Dec 2019, 19:00 Gil Barmwater, > wrote:


Thanks for the feedback Rony. Anyone else have any comments? If
not, I will start posting comments on the issues I have found
shortly. My goal is to develop a package containing the tools that
anyone can download and install that will allow them to build our
docs on Windows 10 from a fresh checkout from SourceForge with
minimal changes to those files.

On 12/10/2019 12:45 PM, Rony G. Flatscher wrote:

Wow, that is *fantastic* news!! Also, looking at your readme.pdf
it looks terrific IMHO!

Very curious what you have come up with to be able to generate
the ooRexx 5.0 documentation yourself� (and also about the
questions that you will pose in order to learn about the current
problems from them and become able to build the ooRexx
documentation in the near future and in a future-safe way)!

Kudos!

---rony

On 10.12.2019 18:17, Gil Barmwater wrote:


I know it has been over a month since I posted the note below
but I now have a lot of progress to report! I have obtained the
tools needed to build our docs - they are open source and seem
well supported - and have successfully built one document using
them on Windows 10. There are no dependencies on Publican other
than three files I chose to retain to simplify the transition.
Installing and using the tools was pretty painless but in doing
so I uncovered a number of issues with our documents, most of
which are due to our use of Publican and what it does "under the
covers". Rather than turning this email into a "book", I will
send separate notes on each issue and the changes needed in
order to use the new tools. In the meantime, here
 is a
link to a file in my Dropbox for the readme.pdf that I built.
Once the link opens in your browser, you can click on the ...
icon on the right which will open a menu that will allow you to
download the file. If you then compare it to the readme.pdf that
is in the docs folder of your 5.0.0 ooRexx installation or the
Files section on SourceForge, you will see it is (almost)
identical. The differences are 1) the text has been updated in
section 2.2, 2) the Copyright dates on the first page now show
-2019, 3) the flow of the text in some sections is slightly
different, in some cases causing text to flow to the next page,
and 4) the Table of Contents has more levels listed. I did not
feel that either of the last two items were worth pursuing. Let
me know what you think after you've had a look.

Gil B.


--
Just so everyone doesn't think I've abandoned this effort, I am
pursuing another approach to building the docs. You can expect
an update when I've made some more progress.


On 11/4/2019 4:16 PM, Gil Barmwater wrote:

?I will go back to docbook.org  and do some
more reading before proceeding any further with Pandoc.

-- 
Gil Barmwater




___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net  

https://lists.sourceforge.net/lists/listinfo/oorexx-devel


--