Re: wiki pages design

From: Adrian A. (a.adrian.tec..mail.com)
Date: Wed Feb 17 2010 - 06:06:23 EST

  • Next message: Aristedes Maniatis: "Re: wiki pages design"

    >> If you decide to use Docbook, I would gladly help with the conversion
    >> of the Cayenne documentation.
    >
    > Before we decide, I guess somebody has to build a prototype showing how
    > that would work using a few pages from the User Guide. I am interested
    > in the following aspects. Ari or Adrian could you please comment:
    >
    > * Authoring process (do we have to edit XML by hand?)
    The authoring process can be done in many ways - from manual XML edit
    with smart assistance from the IDE (or various IDE plug-ins), to using
    various WYSIWYG tools.

    There are a few commercial WYSIWYG tools, but fortunately all I've
    tried, had also free licenses for open source projects. E.g.
    http://www.xmlmind.com/xmleditor/ was very efficient for me.

    Even OpenOffice seems to have some Docbook support.

    Regarding the typical workflow, I would differentiation:
    1. Writing allot of documentation at once in one place (e.g. one entire
    chapter, or at least more than one page), gives the WYSIWYG tool
    an advantage (but I suppose this would be rare for Cayenne now).
    2. Making small (one or two phrases, or even a few words)
    additions/chanegs, makes the direct edit in the IDE faster.

    > * Maven support
    I can't tell much about Maven, but with ANT for the Click like template
    (that I'm reusing allot for it's simplicity), it requires just typing:
    %> ant get-deps
    %> ant
    and everything gets generated.

    > * I assume the same doc source can be published as HTML on the web, and
    > as PDF for the release.
    Yes. For Click it generates 3 types of files (2 HTML and 1 PDF). See
    here the results 3 type of results:
    http://click.apache.org/docs/user-guide.html

    > What does it take to wrap HTML in our site
    > template? A Velocity template I guess?
    Yes, Velocity would do it too.
    XSite and SiteMesh are also good, but there are many
    tools that can 're-decorate' HTML content statically or dynamically.

    Also, if you would like to see a "prototype Docbook" it in action, I
    would suggest taking a look at the Click documentation - since it's a
    very good prototype (IMHO), and build it from source to see the process.
    You can checkout from here:
    http://svn.apache.org/repos/asf/click/trunk/click/documentation/
    and build with the steps I described above in the "xdocs" subdirectory.

    Adrian.



    This archive was generated by hypermail 2.0.0 : Wed Feb 17 2010 - 06:07:29 EST