xd:doc documentation generation and maven
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
I would really like this as well. Add my vote to this :). Jostein On 8 December 2015 at 17:14, <cmarchand@oxiane.com> 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 oXygen-user@oxygenxml.com https://www.oxygenxml.com/mailman/listinfo/oxygen-user
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, cmarchand@oxiane.com 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 oXygen-user@oxygenxml.com 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:gkholman@CraneSoftwrights.com | 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
Thanks Ken, for these informations. It sounds it is a good start point for my needs. I will work on this, and then I'll come back on the list to explain what's done. Thanks again, Ken, for your help. Best regards, Christophe Le 08/12/2015 21:14, G. Ken Holman a écrit :
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, cmarchand@oxiane.com 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 oXygen-user@oxygenxml.com 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:gkholman@CraneSoftwrights.com | 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
Hi, It hasn't been discussed, so I thought it's worth mentioning that besides the GUI dialog for generating XSLT documentation, Oxygen also has a command line tool that generates XSLT documentation. You could run this tool as a Jenkins task. The GUI can be used to export a settings/configuration file: http://www.oxygenxml.com/doc/versions/17.1/ug-editor/index.html#topics/docum... The configuration file can then be used with the command line tool: http://www.oxygenxml.com/doc/versions/17.1/ug-editor/index.html#topics/docum... You can either use a config file (single argument) or specify the individual arguments in the command line. The arguments that the tool accepts are listed when you run it in the command line:
stylesheetDocumentation xslFile [ [-cfg:configFile] | [[-out:outputFile] [-format:<value>] [-xsl:customFormatXslFile] [-split:<value>] [-openInBrowser:<value>]] | [-help | --help | -h | --h]
Where: stylesheetFile = the XSL file -cfg:configfile = the configuration file. It contains the output file, split method, output format options and some advanced options regarding the included components and components details. If an external configuration file is specified all other supplied arguments except the XSL file will be ignored. You can create such a file in the Oxygen "XSL Stylesheet Documentation" dialog. See the Oxygen user manual for additional information on how to create one.
-out:outputFile = the file where the generated documentation will be saved. By default it is the name of the stylesheet file with 'html' extension. -format:<value> = the output format type used when generating the documentation. value = [html | custom] html = generate documentation in HTML format. custom = generate documentation in a custom format.
-xsl:<customFormatXslFile> = the XSL file to be applied on the intermediate xml format. If there is no xsl file provided then the result will be in the HTML format. -split:<value> = the split method used when generating the documentation. Splitting is recommended for large stylesheets value = [none | component | location]. none = generate one single output file. component = generate an output file for every component in the stylesheet. location = generate an output file for every stylesheet location. By default the used method is 'none' -openInBrowser:<value> = open the result of the transformation in browser. value = [true | false]. true = open the resulted file in browser. false = do not open the resulted file in browser. By default the value is false.
-help | --help | -h | --h = show this help.
Example: stylesheetDocumentation example.xsl -out:stylesheetDocumentation.html -format:custom -xsl:customFormat.xsl -split:location
Regards, Adrian On 09.12.2015 10:55, Christophe Marchand wrote:
Thanks Ken, for these informations. It sounds it is a good start point for my needs. I will work on this, and then I'll come back on the list to explain what's done.
Thanks again, Ken, for your help.
Best regards, Christophe
Le 08/12/2015 21:14, G. Ken Holman a écrit :
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, cmarchand@oxiane.com 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 oXygen-user@oxygenxml.com 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:gkholman@CraneSoftwrights.com | 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
_______________________________________________ oXygen-user mailing list oXygen-user@oxygenxml.com https://www.oxygenxml.com/mailman/listinfo/oxygen-user
-- Adrian Buza oXygen XML Editor and Author Support Tel: +1-650-352-1250 ext.2020 Fax: +40-251-461482 support@oxygenxml.com
Thanks a lot for this complete description ! Best regards, Christophe Le 11/12/2015 10:46, Oxygen XML Editor Support (Adrian Buza) a écrit :
Hi,
It hasn't been discussed, so I thought it's worth mentioning that besides the GUI dialog for generating XSLT documentation, Oxygen also has a command line tool that generates XSLT documentation. You could run this tool as a Jenkins task.
The GUI can be used to export a settings/configuration file: http://www.oxygenxml.com/doc/versions/17.1/ug-editor/index.html#topics/docum...
The configuration file can then be used with the command line tool: http://www.oxygenxml.com/doc/versions/17.1/ug-editor/index.html#topics/docum...
You can either use a config file (single argument) or specify the individual arguments in the command line. The arguments that the tool accepts are listed when you run it in the command line:
stylesheetDocumentation xslFile [ [-cfg:configFile] | [[-out:outputFile] [-format:<value>] [-xsl:customFormatXslFile] [-split:<value>] [-openInBrowser:<value>]] | [-help | --help | -h | --h]
Where: stylesheetFile = the XSL file -cfg:configfile = the configuration file. It contains the output file, split method, output format options and some advanced options regarding the included components and components details. If an external configuration file is specified all other supplied arguments except the XSL file will be ignored. You can create such a file in the Oxygen "XSL Stylesheet Documentation" dialog. See the Oxygen user manual for additional information on how to create one.
-out:outputFile = the file where the generated documentation will be saved. By default it is the name of the stylesheet file with 'html' extension. -format:<value> = the output format type used when generating the documentation. value = [html | custom] html = generate documentation in HTML format. custom = generate documentation in a custom format.
-xsl:<customFormatXslFile> = the XSL file to be applied on the intermediate xml format. If there is no xsl file provided then the result will be in the HTML format. -split:<value> = the split method used when generating the documentation. Splitting is recommended for large stylesheets value = [none | component | location]. none = generate one single output file. component = generate an output file for every component in the stylesheet. location = generate an output file for every stylesheet location. By default the used method is 'none' -openInBrowser:<value> = open the result of the transformation in browser. value = [true | false]. true = open the resulted file in browser. false = do not open the resulted file in browser. By default the value is false.
-help | --help | -h | --h = show this help.
Example: stylesheetDocumentation example.xsl -out:stylesheetDocumentation.html -format:custom -xsl:customFormat.xsl -split:location
Regards, Adrian
On 09.12.2015 10:55, Christophe Marchand wrote:
Thanks Ken, for these informations. It sounds it is a good start point for my needs. I will work on this, and then I'll come back on the list to explain what's done.
Thanks again, Ken, for your help.
Best regards, Christophe
Le 08/12/2015 21:14, G. Ken Holman a écrit :
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, cmarchand@oxiane.com 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 oXygen-user@oxygenxml.com 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:gkholman@CraneSoftwrights.com | 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
_______________________________________________ oXygen-user mailing list oXygen-user@oxygenxml.com https://www.oxygenxml.com/mailman/listinfo/oxygen-user
participants (5)
-
Christophe Marchand -
cmarchand＠oxiane.com
-
G. Ken Holman -
Jostein Austvik Jacobsen -
Oxygen XML Editor Support (Adrian Buza)