incubator-odf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Tilton <>
Subject Re: ODF Command Line Tools -- Request for community feedback
Date Sun, 01 Jul 2012 21:30:35 GMT
Hi Rob,

I just pushed to Github, please see below for an explanation of the
changes and some questions regarding next steps.

On Sun, Jun 3, 2012 at 12:47 PM, Rob Weir <> wrote:
> OK.  Thanks for trying.  Maven is great for managing Java project
> dependencies.  Well, at least for pure Java projects targeting
> standard Java outputs like JAR's, WAR's, EAR's, etc.  But the
> Java/JRuby combination may be more complicated.
> I'm using Ubuntu 11.04 with bash.  It isn't liking parts of that
> script.   But I was able to modify it as follows and it worked fine:
> #!/bin/sh
> if [ ! -d ./jars ]; then
>   echo "Downloading jars"
>   mkdir -p ./jars
>   cd jars
>   wget\
>   for targz in *.tar.gz; do
>     echo "Extracting $targz"
>     tar zxf $targz
>   done
>   cd ..
> fi
> echo "Running test"
> JAVA_HOME="$(dirname $(dirname $(readlink -f $(which java))))"
> echo "set JAVA_HOME to $JAVA_HOME"
> CLASSPATH=./jars/xerces-2_11_0/xercesImpl.jar:./jars/xerces-2_11_0/xml-apis.jar:./jars/odftoolkit-0.5-incubating/simple-odf-0.7-incubating.jar:./jars/odftoolkit-0.5-incubating/odfdom-java-0.8.8-incubating.jar
> export CLASSPATH
> jruby lib/oclt.rb

I incorporated your portability changes to, and renamed it to, to reflect the fact that it doesn't actually run the code --
it merely downloads jars and sets environment variables.  To run the
code from the odf-command-line-tools directory, type:

  source ./setup && jruby main.rb

"source" is necessary because the script needs to export shell
variables in the parent shell (i.e., not a subshell).

If you want to use rdoc to build the documentation you may need to run:

  % jruby -S gem install rdoc

before running

  % rdoc --main *

from the top level directory (odf-command-line-tools).

> Two things: build env and runtime env.  For runtime env we should be
> cross platform, right?  For bulld env, cross platform is ideal, but I
> would not get bogged down on that.  Linux is fine.

Yes, Linux for build only; runtime will be cross-platform.  Added to TODO

> I'm looking forward to seeing more on the DSL.

The initial version of the DSL has support for generating new Text
documents;  loading modifying existing Text documents, iterating over
Paragraphs, changing mode and font attributes of new Paragraphs ...
This first version should give you a flavor of what the DSL might
eventually look like, and I hope it is general enough that we can
easily add other document types (e.g., Presentation).

It's made up of 2 parts:  the DSL proper (lib/oclt.rb) and a client
script (main.rb).

Assuming you're okay with what I've done so far, I'd like the
discussion to focus on how the mapping of DSL methods => SimpleAPI
methods should look.  A 1-1 mapping works "out of the box" with the
way the DSL is currently written.  I.e., any SimpleAPI TextDocument
method can now be called from the DSL, and will work.

So if we don't want to change the interface/API, all that's left to do
is write documentation and more examples.  But that won't provide much
of an improvement over the original Java API, only those benefits
which Ruby provides at the most basic level before any "sugar" is
applied.  In other words, while a 1-1 mapping works, it leads to
unnecessary initialization, overall verbosity, and (IMHO) is exactly
what a good DSL should seek to avoid!

As a next step, I propose creating a more concise set of keywords for
the TextDocument API, and working from there.  I'm hoping we can
iterate very fast now that there is a working version.  If we can come
up with (or better yet, find) some conventions for how to map a
standard API to a DSL, I can use that and hit the list when I have
specific questions.

For an example of what I'm talking about, do we really need to say
"set_horizontal_alignment(HorizontalAlignmentType)" or will "center"
suffice?  Should that really be done instead as a parameter in
add_paragraph()?  (e.g., doc.add_paragraph(:alignment => :center)).
Should we let it work both ways for flexibility

At the same time, we don't want to take the sugar too far -- the
interface should be logical to end users without being too "cute".  A
couple of examples of things I changed/added are:

  page_break instead of add_page_break; paragraphs as a new iterable method.

The heavy lifting in the code is currently being done in the file
lib/oclt.rb, specifically the method_missing call.  Inside I have some
logic that tests whether a certain method exists at runtime, and if it
does, delegates appropriately.  If the method doesn't exist the
program bombs out, but there's no reason not to make it do something
more intelligent, like search the SimpleAPI for a method which is
similar to or begins with the given method name, and then perhaps give
the user an informative error message.

More formally, I think the code as written is (loosely) an
implementation of the Adapter pattern
( but using open classes
rather than an explicit adapter class.  In ruby this can be done a
number of ways, I was going for brevity.

I invite your feedback, and the rest of the community too.  Thanks and
enjoy the 4th!


View raw message