incubator-odf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <apa...@robweir.com>
Subject Re: ODF Command Line Tools -- Request for community feedback
Date Fri, 06 Jul 2012 13:17:16 GMT
On Sun, Jul 1, 2012 at 5:30 PM, Noah Tilton <noahktilton@gmail.com> wrote:
> Hi Rob,
>
> I just pushed to Github, please see below for an explanation of the
> changes and some questions regarding next steps.
>
>   https://github.com/noah/odf-command-line-tools
>

Great.  I downloaded and gave it a try.  Looks good.

> On Sun, Jun 3, 2012 at 12:47 PM, Rob Weir <robweir@apache.org> 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  http://mirrors.gigenet.com/apache//xerces/j/binaries/Xerces-J-bin.2.11.0.tar.gz\
>>         http://apache.osuosl.org/incubator/odftoolkit/binaries/odftoolkit-0.5-incubating-bin.tar.gz
>>
>>   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 test.sh, and renamed it to
> setup.sh, 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.
>

I noticed that. I had not taken a close look at Ruby before, but I'm
impressed by how that kind of dispatch can be set up with only a
little code.


> 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!
>

Right.  So is your goal to make this me more "idiomatic" Ruby?  Or to
create a DSL that is either Ruby nor Simple API, but something more
oriented to text processing?

When we were designing the Simply API we tried to make it as easy and
intuitive as possible, within the constraints of Java, and using an
imperative programming style.

One idea I had last night -- what if we inverted the problem?  Instead
of a command line script running against the document, what if we put
the script *inside* the document?   Does that help with any kinds of
repetitive tasks, document automation, etc.?  Now the mere location of
the script doesn't matter.  But a side benefit is that a script inside
the document, inline in the text of a document, has a context that the
user defines naturally via their word processor:

"This confirms your order for %widget_count% widget(s)."

This is then processed by a command line took that evaluates
widget-count as a Ruby routine.  Or we want to avoid the user writing
code, what if we ultra-simplified it?  For example, a document
template that had some named styles that expressed both
appearance/presentation as well as behaviour.  Trivial example:  a
list style called "Sorted List".  No word process has this, to my
knowledge.  But we could have that defined as a style.  When the user
applies it, nothing magic occurs.  But later, on the command line, the
document is processed by an app that applies the behaviours implied by
the styles, and writes out a new document.   One could do very simple,
single-step operations that way.  But is there a way to build up more
complicated scenarios like this?   In other words, what helps enable
the power-user, scripter type to get some benefit of document
automation?


> 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
>

Right.

> 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.
>

Right.  All else being equal, it is best to be idiomatic Ruby.

Another question: Are there any other Ruby libraries that it would
make sense to bring in to the mix?  For example, any that are text or
language related, or even NLP?  Google Translate interface?  Stuff
like that that would radically extend the capabilities with little
incremental coding on your part.

> 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
> (http://en.wikipedia.org/wiki/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!
>
>
> --
> Noah

Mime
View raw message