[oXygen-user] xd:doc documentation generation and maven
Christophe Marchand
Fri Dec 11 04:11:45 CST 2015
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/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
>>
>
More information about the oXygen-user
mailing list