Re: PipX, a portable library of XProc pipelines and steps

I'm using xprocspec to test most of my steps in the project I'm currently
working on so that is a good place to look for examples as well:
https://github.com/josteinaj/nordic-epub3-dtbook-migrator/tree/master/nordic-epub3-dtbook-migrator/src/test/xprocspec


Yeah I worked on a DITA-based documentation approach a couple of years ago,
but it didn't turn out very well (it probably didn't help that I didn't
know DITA :P. DITA is not easy to use.). The lesson I learned though is
that since HTML is the format you want to get out, you should probably use
HTML throughout the documentation generator (authoring, intermediate
formats, output). I haven't looked at how xprocdoc or xprocbook is
implemented, maybe they are like that. Also, it is relatively straight
forward to generate some documentation for a single XProc step if you know
the syntax used, but if you want to link the generated documentation with
other steps, and especially if you want to link it to XSLT documentation
etc., it quickly gets complicated. Also, it helps if it looks nice and I'm
not a UI-person.


Jostein


On 20 February 2014 15:51, Romain Deltour <rdeltour@gmail.com> wrote:

> >  Thank you for making me realize that I wasted time on this one :-)
>
> Had you listen to me instead of drinking your beer… I told you in Prague :P
>
> > At first glance, I like the definition of the
> > language, but I think it lacks examples.  As an example, what would be
> > for example the equivalent in XProcSpec of [1] ?
>
> You can have a look at some examples there:
>
> https://github.com/daisy-consortium/xprocspec/tree/master/xprocspec/src/test/xprocspec/tests
>
> Personally I’m not fluent in XProcSpec yet, so I’ll let Jostein chime in
> if he wants.
>
> > How is it implemented?  Is it platform-independent?  Like
> > implemented with XProc only?
>
> Yes, it’s based on XProc and XSLT.
>
> > Do you know if anything exists to generate API documentation based
> > on a p:library and its p:documentation elements? (at least for step
> > declarations)
>
> There’s XProcDoc:
> https://github.com/vojtechtoman/xprocdoc
>
> Jostein also worked on a DITA-based approach at some point, but which was
> never really finalized IIRC.
>
> But for a new project I would consider using something based on
> lightweight markup (AsciiDoc, Markdown), which is far easier to write for
> documentation than any HTML or custom XML.
>
> Romain.
>
> On 20 févr. 2014, at 15:33, Florent Georges <fgeorges@fgeorges.org> wrote:
>
> > On 20 February 2014 09:01, Romain Deltour wrote:
> >
> >>> 4/ a unit test suite, for simple tests
> >
> >> Have you considered using XProcSpec ?
> >> http://daisy-consortium.github.io/xprocspec/
> >
> >  Thank you for making me realize that I wasted time on this one :-)
> > Actually I looked for it but could not find it again, so assumed it
> > was not public.  At first glance, I like the definition of the
> > language, but I think it lacks examples.  As an example, what would be
> > for example the equivalent in XProcSpec of [1] ?  Basically it tests
> > the following:
> >
> >    <pipx:parameter param-name="foo">
> >       <p:with-param name="foo" select="'bar'"/>
> >    </pipx:parameter>
> >      --> <param name="foo">bar</param>
> >
> >    <pipx:parameter param-name="foo" required="true">
> >       <p:with-param name="foo" select="'bar'"/>
> >    </pipx:parameter>
> >      --> <param name="foo">bar</param>
> >
> >    <pipx:parameter param-name="foo" required="true">
> >       <p:input port="parameters">
> >          <p:empty/>
> >       </p:input>
> >    </pipx:parameter>
> >      --> error pipx:no-parameter
> >
> >  How is it implemented?  Is it platform-independent?  Like
> > implemented with XProc only?
> >
> >>> 2/ to document precisely each step in the sources using
> >>>    p:documentation
> >>> 3/ a simple documentation generation for the website (using
> >>>    documentation from 2/)
> >
> >  Do you know if anything exists to generate API documentation based
> > on a p:library and its p:documentation elements? (at least for step
> > declarations)
> >
> >  Regards,
> >
> > --
> > Florent Georges
> > http://fgeorges.org/
> > http://h2oconsulting.be/
> >
> > [1]https://github.com/fgeorges/pipx/blob/master/test/pipx-parameter.xml
>
>