https://github.com/devlauer/docconverter
https://github.com/devlauer/docconverter
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/devlauer/docconverter
- Owner: devlauer
- License: apache-2.0
- Created: 2018-10-03T12:47:26.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-05-05T21:30:35.000Z (about 1 year ago)
- Last Synced: 2024-05-07T18:06:05.129Z (about 1 year ago)
- Language: Java
- Size: 384 KB
- Stars: 1
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.adoc
- Changelog: Changelog.adoc
- License: LICENSE
Awesome Lists containing this project
README
= docconverter project
:docconverter-version: 1.0.6
image:https://sonarcloud.io/api/project_badges/measure?project=devlauer_docconverter&metric=ncloc["Lines of Code", link="https://sonarcloud.io/summary/new_code?id=devlauer_docconverter"]
image:https://sonarcloud.io/api/project_badges/measure?project=devlauer_docconverter&metric=security_rating["Security Rating", link="https://sonarcloud.io/summary/new_code?id=devlauer_docconverter"]
image:https://sonarcloud.io/api/project_badges/measure?project=devlauer_docconverter&metric=vulnerabilities["Vulnerabilities", link="https://sonarcloud.io/summary/new_code?id=devlauer_docconverter"]
image:https://sonarcloud.io/api/project_badges/measure?project=devlauer_docconverter&metric=sqale_rating["Maintainability Rating", link="https://sonarcloud.io/summary/new_code?id=devlauer_docconverter"]
image:https://sonarcloud.io/api/project_badges/measure?project=devlauer_docconverter&metric=coverage["Coverage", link="https://sonarcloud.io/summary/new_code?id=devlauer_docconverter"]
image:https://github.com/devlauer/docconverter/actions/workflows/verify.yml/badge.svg["mvn verify"]
== Description
docconverter is a universal Java library which helps to convert
from one document format to another document format.
This is achieved by delegating the conversion process to other
Java libraries which understand concrete parts of this conversion
for one special document format.
.The docconverter project itself consists of
- an api, which standardizes all classes needed for the conversion process
- several implementations, which are used by the api classes and do the
concrete conversion if they are dropped into the classpath
- a maven plugin, which helps to use this library during a maven build process
== Usage library
The api of this library is a fluent api. You simply need to obtain an instance
of the ConversionJobFactory create a conversion job, add your input streams or
files, declare your input MIME type, declare your wanted output MIME type and
start conversion. E.g.:
[source,java]
----
ConversionJobFactory.getInstance()
.createEmptyConversionJob()
.fromStreams(inputList)
.fromMimeType(MimeTypeConstants.APPLICATION_XHTML)
.toMimeType(MimeTypeConstants.APPLICATION_PDF).convert();
----
You will get a Future
de.elnarion.util
docconverter-api
{docconverter-version}
----
and the needed implementation, e.g.
[source, xml,subs="attributes,verbatim"]
----
de.elnarion.util
docconverter-html2pdf
{docconverter-version}
----
to your pom.xml
== Usage maven plugin
If you want to use the docconverter maven plugin for conversions during a maven build,
you need to configure this plugin as any normal maven plugin as part of your build and
add this plugin specific configuration:
* outputDirectory -
the target folder where all resulting files are written; defaults to target/generated-docs
* sourceDirectory -
the folder where all input files are located (including all subfolders); defaults to /src/main/doc
* sourceMimeType -
the MIME type of all input files
* targetMimeType -
the MIME type of all output files
* outputFileending -
the file extension used for all target filenames
* sourceDocumentExtensions -
a comma separated list used for filtering all files of the source directory by their file extension
* sourceDocument -
optional parameter which can be used to convert only one single file
* conversionParameters -
optional parameters which are passed to the concrete conversion implementation
For each requested document conversion you need to add the concrete docconverter implementation as plugin dependency.
[source, xml,subs="attributes,verbatim"]
----
docconverter-maven-plugin
de.elnarion.maven
{docconverter-version}
some-id
wanted maven phase
convert
wanted target directory
directory of all input files
input MIME type
output MIME type
output extension
input extension for filtering files, e.g. html
de.elnarion.util
docconverter-someimplementation
{docconverter-version}
----
Here is an example of a Maven project (pom.xml) which uses this maven plugin to convert all
xhtml files in the src/main/testfiles folder to pdf files in the target folder target/xhtml2pdf:
[source,xml,subs="attributes,verbatim"]
----
4.0.0
de.elnarion.sample
sample.maventest
0.0.1-SNAPSHOT
docconverter-maven-plugin
de.elnarion.maven
{docconverter-version}
html2pdf
generate-resources
convert
${basedir}/target/xhtml2pdf
${basedir}/src/main/testfiles
application/xhtml+xml
application/pdf
pdf
xhtml
adoc2adoc
generate-resources
convert
${basedir}/target/adoc
${basedir}/src/main/testfiles
text/x.asciidoc
text/x.asciidoc
adoc
adoc
.*include\:\:\.\/.*\[\].*
de.elnarion.util
docconverter-html2pdf
{docconverter-version}
de.elnarion.util
docconverter-adoc2adoc
{docconverter-version}
----
== Supported conversions
This project currently supports the following MIME type conversions:
* _text/html_, _application/xhtml+xml_ to _application/pdf_ via *_docconverter-html2pdf_*
* _application/pdf_ to _image/jpeg_ via *_docconverter-pdf2jpg_*
* _text/x.asciidoc_ to _text/x.asciidoc_ (includes all included separate files directly in
your target file) via *_docconverter-adoc2adoc_*
* _text/html, _application/xhtml+xml_ to _application/vnd.openxmlformats-officedocument.wordprocessingml.document_
via *_documentconverter-html2docx_*
== Licensing
This software is licensed under the http://www.apache.org/licenses/LICENSE-2.0.html[Apache Licence, Version 2.0].
Note that docconverter has several dependencies which are not licensed under the Apache License.
Note that using docconverter comes without any (legal) warranties.
== Versioning
This plugin uses sematic versioning. For more information refer to http://semver.org/[semver].
== Changelog
This plugin has a dedicated Changelog.
== Reporting bugs and feature requests
Use GitHub issues to create your issues.
== Source
Latest and greatest source of docconverter can be found on https://github.com/devlauer/docconverter[GitHub]. Fork it!