[RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

[RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Rony G. Flatscher
Is there anyone by chance who has worked with DocBook (<https://en.wikipedia.org/wiki/DocBook>,
<https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>, <http://docbook.org/>) or who
would be interested to learn and to work with this infrastructure?

As the ooRexx documentation is in DocBook format, currently Publican is used for formatting. Any
(little) improvements in the area of ooRexx documentation (e.g. creating HTML-renderings of the
PDF-books) could need some helping hands.

Also anyone who has knowledge or would be willing to research the needed pieces for good working
DocBook editors/processors (preferably opensource) on Linux/Windows/MacOSX could probably give
valuable help in this (important) corner!

---rony


_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Haluk POLAT
Dear Rony;

Past of DocBook goes to 10 years ago. In Rexx.org page, documentation of some project has been created as DocBook. But modern software projects prefer PDF and HTML 5 formats.

If you use XML based HTML documentation, you can use XHTML format! 

Create your documentation as HTML 5 and make some little changes for XHTML.

Please search in Google "xhtml" and click link of W3 Schools page. It is second link of results of Google search.

Sincerely...
--
Haluk POLAT
530 Sok. 30/2 - Şirinyer - 35150 İZMİR
+90 - 532 - 385 09 93
+90 - 541 - 385 09 93

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Rony G. Flatscher
Dear Haluk,

DocBook is XML-based and allows for generating PDF, HTML and the like from one single text source. The supplied links (<https://en.wikipedia.org/wiki/DocBook>, <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>, <http://docbook.org/>) are starting points for getting an overview

If you have experiences in creating and/or processing XML marked-up texts, maybe you would be able and willing to help out in this area?

Cheers

---rony


On 12.09.2017 14:58, Haluk POLAT wrote:
Dear Rony;

Past of DocBook goes to 10 years ago. In Rexx.org page, documentation of some project has been created as DocBook. But modern software projects prefer PDF and HTML 5 formats.

If you use XML based HTML documentation, you can use XHTML format! 

Create your documentation as HTML 5 and make some little changes for XHTML.

Please search in Google "xhtml" and click link of W3 Schools page. It is second link of results of Google search.

Sincerely...
--
Haluk POLAT
530 Sok. 30/2 - Şirinyer - 35150 İZMİR
+90 - 532 - 385 09 93
+90 - 541 - 385 09 93


_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Haluk POLAT
Dear Rony,

I don't have any experience about XML and DocBook.

I my software project, I use HTML and PDF format.

Accorrding to in my past knowledge, DocBook has been used very rare in modern software projects.

Some Perl and PHP libraries include some functions that produce PDF output from HTML file.

Sincerely...

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Gil Barmwater
In reply to this post by Rony G. Flatscher
Rony,

A quick search for 'docbook editors' brought up SlickEdit among others. 
I know it is NOT open source but might be worth exploring.  My version
is several years old and does not have that support but I was recently
offered an opportunity to beta-test the upcoming release.  I will check
it out and report back.

Gil
On 9/12/2017 8:16 AM, Rony G. Flatscher wrote:

> Is there anyone by chance who has worked with DocBook (<https://en.wikipedia.org/wiki/DocBook>,
> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>, <http://docbook.org/>) or who
> would be interested to learn and to work with this infrastructure?
>
> As the ooRexx documentation is in DocBook format, currently Publican is used for formatting. Any
> (little) improvements in the area of ooRexx documentation (e.g. creating HTML-renderings of the
> PDF-books) could need some helping hands.
>
> Also anyone who has knowledge or would be willing to research the needed pieces for good working
> DocBook editors/processors (preferably opensource) on Linux/Windows/MacOSX could probably give
> valuable help in this (important) corner!
>
> ---rony
>
>
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members
>

--
Gil Barmwater

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Dan Carter
My SlickEdit 2016 shows, under Tools;Options;Languages;XML/Text Languages
configurations for DocBook, DTD, PDF, PostScript, TeX, etc.  
The editor can be configured to work with files for any of these and several
other documentation and text processors.  It is pricey, but the
less-expensive SE/CORE version, which runs under Eclipse (my preferred
version) has all these features and sells for just under $100.  

I use both versions, and I recommend them highly.  I also have high regard
for their support.  

1/137

-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of Gil Barmwater
Sent: Tuesday, September 12, 2017 09:18
To: [hidden email]
Subject: Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to
help in this corner?

Rony,

A quick search for 'docbook editors' brought up SlickEdit among others. I
know it is NOT open source but might be worth exploring.  My version is
several years old and does not have that support but I was recently offered
an opportunity to beta-test the upcoming release.  I will check it out and
report back.

Gil
On 9/12/2017 8:16 AM, Rony G. Flatscher wrote:
> Is there anyone by chance who has worked with DocBook
> (<https://en.wikipedia.org/wiki/DocBook>,
> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>,
> <http://docbook.org/>) or who would be interested to learn and to work
with this infrastructure?

>
> As the ooRexx documentation is in DocBook format, currently Publican
> is used for formatting. Any
> (little) improvements in the area of ooRexx documentation (e.g.
> creating HTML-renderings of the
> PDF-books) could need some helping hands.
>
> Also anyone who has knowledge or would be willing to research the
> needed pieces for good working DocBook editors/processors (preferably
> opensource) on Linux/Windows/MacOSX could probably give valuable help in
this (important) corner!
>
> ---rony
>
>
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members
>

--
Gil Barmwater

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members


_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Haluk POLAT
Dear Rony;

OpenOffice and LibreOffice produce DocBook file from DOCX and ODT file.

Please use it. I hope that you like it.

Sincerely...
--
Haluk POLAT
530 Sok. 30/2 - Şirinyer - 35150 İZMİR
+90 - 532 - 385 09 93
+90 - 541 - 385 09 93

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

LesK
Administrator
In reply to this post by Rony G. Flatscher
A brief reading of the Wickipedia entry makes it sound like all the
pieces for what you need to do (like generate HTML, or even WebHTML) are
already out there in the Open world.

Of course by the time you finish putting all the pieces together, you
have the equivalent of IBM's Bookmaster using GML, without the macro
capability!

I'm always amused about the pc world re-inventing things so they don't
look like what's on the mainframe, and then expending all the effort to
produce what the mainframe has been doing for years!

Les

On 9/12/2017 8:16 AM, Rony G. Flatscher wrote:

> Is there anyone by chance who has worked with DocBook (<https://en.wikipedia.org/wiki/DocBook>,
> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>, <http://docbook.org/>) or who
> would be interested to learn and to work with this infrastructure?
>
> As the ooRexx documentation is in DocBook format, currently Publican is used for formatting. Any
> (little) improvements in the area of ooRexx documentation (e.g. creating HTML-renderings of the
> PDF-books) could need some helping hands.
>
> Also anyone who has knowledge or would be willing to research the needed pieces for good working
> DocBook editors/processors (preferably opensource) on Linux/Windows/MacOSX could probably give
> valuable help in this (important) corner!
>
> ---rony
>
>
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members
>
_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Dan Carter
Hear, hear, Les!  Whenever I code C I remember wordmarks.

1/137


-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of Les Koehler
Sent: Tuesday, September 12, 2017 11:06
To: [hidden email]
Subject: Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to
help in this corner?

A brief reading of the Wickipedia entry makes it sound like all the pieces
for what you need to do (like generate HTML, or even WebHTML) are already
out there in the Open world.

Of course by the time you finish putting all the pieces together, you have
the equivalent of IBM's Bookmaster using GML, without the macro capability!

I'm always amused about the pc world re-inventing things so they don't look
like what's on the mainframe, and then expending all the effort to produce
what the mainframe has been doing for years!

Les

On 9/12/2017 8:16 AM, Rony G. Flatscher wrote:
> Is there anyone by chance who has worked with DocBook
> (<https://en.wikipedia.org/wiki/DocBook>,
> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>,
> <http://docbook.org/>) or who would be interested to learn and to work
with this infrastructure?

>
> As the ooRexx documentation is in DocBook format, currently Publican
> is used for formatting. Any
> (little) improvements in the area of ooRexx documentation (e.g.
> creating HTML-renderings of the
> PDF-books) could need some helping hands.
>
> Also anyone who has knowledge or would be willing to research the
> needed pieces for good working DocBook editors/processors (preferably
> opensource) on Linux/Windows/MacOSX could probably give valuable help in
this (important) corner!
>
> ---rony
>
>
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members
>
_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members


_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Chip Davis
Administrator
In reply to this post by LesK
In support of Les' musing, has anyone explored the possibility of
getting some donated time from a sympathetic z/VM shop?

-Chip-

On 9/12/2017 1:05 PM, Les Koehler wrote:

> A brief reading of the Wickipedia entry makes it sound like all the
> pieces for what you need to do (like generate HTML, or even WebHTML)
> are already out there in the Open world.
>
> Of course by the time you finish putting all the pieces together, you
> have the equivalent of IBM's Bookmaster using GML, without the macro
> capability!
>
> I'm always amused about the pc world re-inventing things so they don't
> look like what's on the mainframe, and then expending all the effort to
> produce what the mainframe has been doing for years!
>
> Les
>
> On 9/12/2017 8:16 AM, Rony G. Flatscher wrote:
>> Is there anyone by chance who has worked with DocBook
>> (<https://en.wikipedia.org/wiki/DocBook>,
>> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>,
>> <http://docbook.org/>) or who
>> would be interested to learn and to work with this infrastructure?
>>
>> As the ooRexx documentation is in DocBook format, currently Publican
>> is used for formatting. Any
>> (little) improvements in the area of ooRexx documentation (e.g.
>> creating HTML-renderings of the
>> PDF-books) could need some helping hands.
>>
>> Also anyone who has knowledge or would be willing to research the
>> needed pieces for good working
>> DocBook editors/processors (preferably opensource) on
>> Linux/Windows/MacOSX could probably give
>> valuable help in this (important) corner!
>>
>> ---rony
>>
>>
>> _______________________________________________
>> rexxla-members mailing list -- mailto:[hidden email]
>> http://rexxla.org/mailman/listinfo/rexxla-members
>>
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members
>
_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Rene Jansen
Administrator
In reply to this post by Rony G. Flatscher
As you know I am using XeTeX for the NetRexx documentation. The is because I did some typographical work in my youth and I think there is nothing better - and it is free, so you can’t beat the price. Also, I execute NetRexx programs as part of the toolchain, which do clerical work as maintaining version information and running examples, so their *exact* output appears in the book.

I have been interested in DocBook for a long time and have followed the open source offerings for the different DocBook — xslt — fop toolchains. Franky, only the (very expensive) commercial offerings perform as well as TeX; Apache fop was so-so for ages.

As TeX is a bit too academic (and generally too much of everything) for some of my clients, I occasionally use asciidoc, which is a ‘markdown’ (as in simple markup) family language, which translates with a simple command into DocBook, which in turn can be formatted (it is a set of Python scripts) to PDF, html or ebook. Here again, for PDF targets there is a choice of Apache fop or dblatex; dblatex is a DocBook to TeX formatter, and yields better results (imho).

The upside of this last one is: the text is readable while editing (editing docbook xml is a horrible experience regardless of tooling support, and I have hand edited Script/VS, GML, SGML, IPF, and still hand edit Tex source), it still can be used with DocBook toolchains, and (at least on Linux and macos) can be installed with some easy repository commands.

The problem with Publican is that it is very hard to install and configure, and there are no two versions that produce the same output. If it were up to me, the research should include markdown versions like asciidoc, which will greatly simplify the work of the copy editor, with everything (or nearly - that should be the research) needed for producing technical documentation included. The toolchain and output should be identical on all platforms and not as it is now.

best regards,

René.



> On 12 Sep 2017, at 14:16, Rony G. Flatscher <[hidden email]> wrote:
>
> Is there anyone by chance who has worked with DocBook (<https://en.wikipedia.org/wiki/DocBook>,
> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>, <http://docbook.org/>) or who
> would be interested to learn and to work with this infrastructure?
>
> As the ooRexx documentation is in DocBook format, currently Publican is used for formatting. Any
> (little) improvements in the area of ooRexx documentation (e.g. creating HTML-renderings of the
> PDF-books) could need some helping hands.
>
> Also anyone who has knowledge or would be willing to research the needed pieces for good working
> DocBook editors/processors (preferably opensource) on Linux/Windows/MacOSX could probably give
> valuable help in this (important) corner!
>
> ---rony
>
>
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members
Reply | Threaded
Open this post in threaded view
|

Re: [RexxLA] Anyone with DocBook experience, knowhow or willing to help in this corner?

Gil Barmwater
Thanks to a post from Dan Carter, I found that my version of SlickEdit
DOES support a document type of "docbook".  I downloaded a section of
the ooRexx Reference from SF and opened it with SlickEdit.  I looks much
better than it does when viewed at SF. That being said, it still is
"littered" with the tags, making it hard to read or edit.

I'd like to second René's suggestion that we look at alternatives.  I,
for one, would love to be able to easily build our doc's (on Windows) so
that when I discover minor bugs - typos, etc. - I can code a fix, build
a version to verify it, and open a bug WITH a patch!  I know the
committers have more pressing things to do than to research doc bugs so
this might be a way to get these things fixed with a minimum workload
for them.

Gil B.
On 9/12/2017 5:42 PM, René Jansen wrote:

> As you know I am using XeTeX for the NetRexx documentation. The is because I did some typographical work in my youth and I think there is nothing better - and it is free, so you can’t beat the price. Also, I execute NetRexx programs as part of the toolchain, which do clerical work as maintaining version information and running examples, so their *exact* output appears in the book.
>
> I have been interested in DocBook for a long time and have followed the open source offerings for the different DocBook — xslt — fop toolchains. Franky, only the (very expensive) commercial offerings perform as well as TeX; Apache fop was so-so for ages.
>
> As TeX is a bit too academic (and generally too much of everything) for some of my clients, I occasionally use asciidoc, which is a ‘markdown’ (as in simple markup) family language, which translates with a simple command into DocBook, which in turn can be formatted (it is a set of Python scripts) to PDF, html or ebook. Here again, for PDF targets there is a choice of Apache fop or dblatex; dblatex is a DocBook to TeX formatter, and yields better results (imho).
>
> The upside of this last one is: the text is readable while editing (editing docbook xml is a horrible experience regardless of tooling support, and I have hand edited Script/VS, GML, SGML, IPF, and still hand edit Tex source), it still can be used with DocBook toolchains, and (at least on Linux and macos) can be installed with some easy repository commands.
>
> The problem with Publican is that it is very hard to install and configure, and there are no two versions that produce the same output. If it were up to me, the research should include markdown versions like asciidoc, which will greatly simplify the work of the copy editor, with everything (or nearly - that should be the research) needed for producing technical documentation included. The toolchain and output should be identical on all platforms and not as it is now.
>
> best regards,
>
> René.
>
>
>
>> On 12 Sep 2017, at 14:16, Rony G. Flatscher <[hidden email]> wrote:
>>
>> Is there anyone by chance who has worked with DocBook (<https://en.wikipedia.org/wiki/DocBook>,
>> <https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>, <http://docbook.org/>) or who
>> would be interested to learn and to work with this infrastructure?
>>
>> As the ooRexx documentation is in DocBook format, currently Publican is used for formatting. Any
>> (little) improvements in the area of ooRexx documentation (e.g. creating HTML-renderings of the
>> PDF-books) could need some helping hands.
>>
>> Also anyone who has knowledge or would be willing to research the needed pieces for good working
>> DocBook editors/processors (preferably opensource) on Linux/Windows/MacOSX could probably give
>> valuable help in this (important) corner!
>>
>> ---rony
>>
>>
>> _______________________________________________
>> rexxla-members mailing list -- mailto:[hidden email]
>> http://rexxla.org/mailman/listinfo/rexxla-members
> _______________________________________________
> rexxla-members mailing list -- mailto:[hidden email]
> http://rexxla.org/mailman/listinfo/rexxla-members

--
Gil Barmwater

_______________________________________________
rexxla-members mailing list -- mailto:[hidden email]
http://rexxla.org/mailman/listinfo/rexxla-members