You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@corinthia.apache.org by ja...@apache.org on 2015/08/09 11:16:58 UTC
incubator-corinthia git commit: keep text files in sync with release
branch
Repository: incubator-corinthia
Updated Branches:
refs/heads/master d75e045ab -> 71ab85c3e
keep text files in sync with release branch
Project: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/commit/71ab85c3
Tree: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/tree/71ab85c3
Diff: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/diff/71ab85c3
Branch: refs/heads/master
Commit: 71ab85c3ef5807bab6bef6a2a3640fb913a8c510
Parents: d75e045
Author: jani <ja...@apache.org>
Authored: Sun Aug 9 11:16:30 2015 +0200
Committer: jani <ja...@apache.org>
Committed: Sun Aug 9 11:16:30 2015 +0200
----------------------------------------------------------------------
DEVELOPERS | 2 ++
README.md | 87 +++++++++++++++++++++++++++++++++------------------------
2 files changed, 52 insertions(+), 37 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/71ab85c3/DEVELOPERS
----------------------------------------------------------------------
diff --git a/DEVELOPERS b/DEVELOPERS
new file mode 100644
index 0000000..ffa4ab8
--- /dev/null
+++ b/DEVELOPERS
@@ -0,0 +1,2 @@
+** TO BE UPDATED WHEN MAKING A RELEASE BRANCH **
+
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/71ab85c3/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index f15ec4f..85022f7 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,24 @@
# About Apache Corinthia (incubating)
-Corinthia is a library for converting between different word-processing file
-formats. Initially, it supports .docx (part of the OOXML specification), HTML,
-and LaTeX (export-only). The Corinthia project also provides convenience
-executables. The library has shipped as part of
-[UX Write](http://www.uxproductivity.com/) since February 2013.
-
-On December 8, 2014, Corinthia entered the Apache Software
-Foundation
-[incubator](http://incubator.apache.org/incubation/Process_Description.html).
-The
-[accepted proposal](http://wiki.apache.org/incubator/CorinthiaProposal) and
-[incubation status](http://incubator.apache.org/projects/corinthia.html)
-provide incubation background and progress information.
+Corinthia is a set of libraries and tools for dealing with different file
+formats for productivity applications, with an initial focus on word processing.
+The goal of the project is to provide components which developers can easily
+integrate into their own applications and scripts for converting and
+manipulating data in a wide range of formats via a consistent interface.
+
+This is the first public release of Corinthia, and consists of a single core
+library called DocFormats. The library provides two-way conversion between OOXML
+word processing documents (aka Microsoft Word .docx) and HTML. The Microsoft
+Word support has previously been used in commercial applications and is fairly
+mature. Support for other file formats is in development, but not part of this
+release.
+
+The Corinthia project is part of the Apache Software Foundation
+[incubator](http://incubator.apache.org/incubation/Process_Description.html),
+which it entered on December 8, 2014. The [accepted
+proposal](http://wiki.apache.org/incubator/CorinthiaProposal) and [incubation
+status](http://incubator.apache.org/projects/corinthia.html) provide incubation
+background and progress information.
The communication hub of the project is the development mailing list,
@@ -26,17 +32,17 @@ from the email address to receive list messages at. The reply from
the list robot to that address provides confirmation instructions and
information on managing the subscription.
-There are a [Corinthia incubator web
-site](http://corinthia.incubator.apache.org/), a
-[project wiki](http://incubator.apache.org/projects/corinthia.html), and a
-[JIRA issue tracker](https://issues.apache.org/jira/browse/COR).
+Further links:
+- [Corinthia incubator web site](http://corinthia.incubator.apache.org/)
+- [Project wiki](http://incubator.apache.org/projects/corinthia.html), and a
+- [JIRA issue tracker](https://issues.apache.org/jira/browse/COR).
-The sites and documentation for this project are at a preliminary
-stage. Content will be moved to Apache and improved as incubation moves
-along.
+These sites and the documentation for this project are at a preliminary stage.
+Content will be moved to Apache and improved as incubation moves along.
-Meanwhile, there is a [Facebook page](https://www.facebook.com/CorinthiaProject) and a Twitter account, [@ApacheCorinthia](https://twitter.com/ApacheCorinthia).
+There is also a [Facebook page](https://www.facebook.com/CorinthiaProject) and a
+Twitter account, [@ApacheCorinthia](https://twitter.com/ApacheCorinthia).
# License
@@ -57,23 +63,30 @@ LICENSE.txt for details.
There are three major components, in their respective directories:
-* `DocFormats` - the library itself
-* `dfutil` - a driver program used for running [...]
-* automated tests (located in the tests directory)
+* `DocFormats` - file format conversion library
+* `dfconvert` - driver program for performing conversions
+* `dftest` - test harness
-Run dfutil without any command-line arguments to see a list of operations.
-Here is an example of converting a .docx file to HTML, modifying it, and then
-updating the original .docx. Note that it is important, due to how internal
-mapping works, that the .docx file being written is the same file as the
-original; using a new file won't work.
+Run dfconvert without any command-line arguments to see a list of possible
+operations. The following is an example of converting a .docx file to HTML,
+modifying it, and then updating the original .docx file based on the modified
+HTML file. Any content or formatting information that could not be converted to
+HTML (e.g. embedded spreadsheets) will be left untouched.
- dfutil filename.docx filename.html
- vi filename.html # Make some changes
- dfutil filename.html filename.docx
+ dfconvert get report.docx report.html
+ vi report.html # Make some changes
+ dfconvert put report.docx report.html
-If you examine the convertFile function in `dfutil/Commands.c`, you will see
-the main entry points to perform these conversions, which you can call from
-your own program.
+Note that when executing a put operation to update the document, the .docx file
+must be identical to that from which the HTML file was originally generated.
+This is because of assumptions the update process relies on about the
+relationship between elements in the HTML file and their counterparts in the
+.docx file. If you have modified the .docx file between get and put, or execute
+a put on the same file twice, this will be automatically detected and an error
+will be reported.
+
+Look at `consumers/dfconvert/src/main.c` to see how to use the API. The public
+API headers are in the `DocFormats/api/headers/DocFormats` directory.
# Platforms and dependencies
@@ -88,11 +101,11 @@ To build DocFormats, you will need to have the following installed:
# Build instructions
-Corinthia currently builds on Linux, OS X (mac) and Windows. See the [build instructions](https://cwiki.apache.org/confluence/display/Corinthia/Build+instructions).
+Corinthia currently builds on Linux, OS X and Windows. See the [build instructions](https://cwiki.apache.org/confluence/display/Corinthia/Build+instructions).
# Contributing
-Contributors are welcome and prized. Details on how to participate on the
+Contributors are welcome. Details on how to participate on the
project will be posted soon.
Meanwhile, the easiest way to contribute is by subscribing to the development