[oXygen-user] xd:doc documentation generation and maven

[G. Ken Holman]

You don't mention if by "automate" you mean simply to infer a report 
about the structure, or whether you mean to publish embedded 
documentation as a step in the process.

Back in 2004 I published XSLT documentation scaffolding in which one 
uses either DocBook, DITA or XHTML for the prose constructs.  A 
stylesheet then reads the top XSLT stylesheet and reports on the 
entire import/include tree, all named constructs (an alphabetized 
hyperlinked index) and all embedded documentation.  The stylesheet 
also enforces what I think are important XSLT stylesheet writing 
"business rules" to improve the quality of the stylesheets for different uses.

For example, you mention an "XSL Library".  I believe an XSLT library 
should use namespace-qualified names for each and every global named 
construct.  This ensures it can be safely used in anyone else's 
stylesheet without any risk of messing with global=context constructs 
and modes.  Miss one name and a user can mess up the library, so my 
business rules flag any global name that is not namespace-qualified.

In my experience of looking at XSLT stylesheets written by others for 
clients, I have never seen anyone else take advantage of this 
important language feature.  I think it is critically important for 
libraries of template rules.  I tried to reinforce this when I taught XSLT.

If this stylesheet for stylesheets sounds like it might be helpful, 
it is called XSLStyle and it is available as a free resource on our web site:

   http://www.CraneSoftwrights.com/resources/xslstyle/

Once I honed it I used it for *every* client project and I believe it 
helped me create robust work.  Every project was also fully 
documented along the way and when the development was done, not 
treated as a separate project after the fact.

I hope this is helpful.

. . . . . . . . . Ken

At 2015-12-08 17:14 +0100,  wrote:
>Hello,
>
>is there a way to automate a XSL documentation generation  - ideally 
>from a maven project.. ? Is there an entry in Oxygen API to generate 
>such a documentation that a maven plugin - or any other tool - could reuse ?
>
>Well, the purpose is to generate a xsl-library documentation from 
>continuous integration, so it can be done in a jenkins plugin (which 
>is simpler than in a maven plugin).
>
>
>
>Any hint ?
>
>
>
>Best regards,
>
>Christophe
>_______________________________________________
>oXygen-user mailing list
>
>https://www.oxygenxml.com/mailman/listinfo/oxygen-user


--
Check our site for free XML, XSLT, XSL-FO and UBL developer resources |
Free 5-hour lecture:  http://www.CraneSoftwrights.com/links/video.htm |
Crane Softwrights Ltd.             http://www.CraneSoftwrights.com/s/ |
G. Ken Holman                    mailto: |
Google+ profile:       http://plus.google.com/+GKenHolman-Crane/about |
Legal business disclaimers:     http://www.CraneSoftwrights.com/legal |


---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus