[oXygen-user] xd:doc documentation generation and maven
Oxygen XML Editor Support (Adrian Buza)
Fri Dec 11 03:46:05 CST 2015
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/documentation-XSLT-Stylesheet.html
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/documentation-XSLT-Stylesheet-command-line.html
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, 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
>>
>>
>
> _______________________________________________
> oXygen-user mailing list
>
> 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
More information about the oXygen-user
mailing list