Re: [Oorexx-devel] About doc defect 2808222 and call to volunteers

[David A. <dav...@gm...>]

Jean-Louis Faucher wrote:
> Hi,
>
> Mark made a call to volunteers for documentation improvements in a 
> comment of defect 2808222.
> I'm interested to work on the following changes, if the group agrees :
> Convert all the sgml files to XML DocBook (was started by David in 
> tryxsl).
> Use DocBook XSL to generate final doc
>
> PassiveTeX is the current FO processor to generate PDF.
> At work, we use XEP. RenderX offers a personal edition of XEP which 
> targets open-source developers. Don't know if the "small, 
> non-obtrusive stamp at the bottom of each page" is a criteria of non 
> acceptance by the group.
> Otherwise FOP is the natural candidate, sometimes less powerful than 
> XEP (maybe change bars and keep-together PI are not supported, to check)
>
> [Optional]
> I'd like to use an editor like XXE. Currently, the files are included 
> using sgml entities, which is not supported by XXE. If we replace them 
> by <xi:include> then the XXE editor will be a good candidate for 
> edition. It's free of use for open-source projects.
>
> [Not a priority]
> About the railroads, assuming we want to keep them in the generated doc...
> XXE has an interesting feature that illustrates what could be done for 
> railroads : the DocBook file can reference external files (TeX, Dot, 
> Groff, Pic...) which are converted on the fly to images, assuming you 
> have parameterized the editor to launch the right system command. What 
> you see in the editor is the image, not the source.
> Railroads can be seen has a graphical representation, i.e. could be 
> generated as image from a source more easy to edit. We can probably 
> find tools that generate railroads from a text source like BNF, MFC 
> syntax in TRL or other.
> See 
> http://jean-louis.faucher.perso.neuf.fr/DocBook/transform_images.zip 
> for illustration (no railroad there).
>
> Whatever the decision of the group, replacing the railroads by 
> something else will be a huge work...
> A grep "^>>-" in the doc files give these numbers of railroads :
> oodialog : 933
> ootest : 26
> rexxpg : 186
> rexxref : 908
> rxftp : 33
> rxmath : 26
> rxsock : 67
> winextensions : 156
> Total = 2335
>
> Jean-Louis
>
> ------------------------------------------------------------------------
>
> ------------------------------------------------------------------------------
> Are you an open source citizen? Join us for the Open Source Bridge conference!
> Portland, OR, June 17-19. Two days of sessions, one day of unconference: $250.
> Need another reason to go? 24-hour hacker lounge. Register today!
> http://ad.doubleclick.net/clk;215844324;13503038;v?http://opensourcebridge.org
> ------------------------------------------------------------------------
>
> _______________________________________________
> Oorexx-devel mailing list
> Oor...@li...
> https://lists.sourceforge.net/lists/listinfo/oorexx-devel
>   
Jean-Louis -

I wanted to address some of the items in you list so you don't spend a 
lot of time on research only to find out you wasted your tome.

First and foremost, The docs are in XML format already. If you look at 
the top of every doc you will see that it has an XML DTD, not an SGML 
DTD. The sgml file extension is a left over artifact of when we were 
using an SGML DTD. The docbook processor only looks at the DTD so the 
file extension is completely ignored.

Second, we are currently using an SGML processor to create the documents 
instead of an XML processor because I have not been able to find a 
satisfying XML processor that is platform independent. And please don't 
suggest a Java-based processor. So far, no XML processor I have tried 
produces docs of the quality that the SGML processor produces and every 
XML processor brings with it a new set of problems that are not easily 
resolved, and believe me, I have tried.

Third, I would like to address the page break problem in the PDF 
versions of the docs. Unfortunately, neither the SGML or the XML 
processors are able to produce documents without page breaks at bad 
locations. Part of this problem is the separation of the document from 
the formated output that is inherent in these types of document 
processors. Think about this for a moment and you will observer that 
specifying a page break in the input document is a really bad idea since 
we never know just what kind of output document we will be producing 
i.e. a specified page break in HTML output makes no sense at all.

Fourth, replacing the current include mechanism will break the documents 
when an SGML processor is used. So until we can come to a consensus 
about an XML processor, I am against switching this to a pure XML mechanism.

Having said all of the above, I hope I did not discourage you from 
getting more involved with the documentation. There are a lot of things 
that need to be done (like the replacement of the RR diagrams). And 
please feel free to try and come up with solutions to the above 
problems. If you can, you are better at this than me :-)

David Ashley