How can I use bnd directives instruction from maven-bundle-plugin? bnd directives are starting with a '-' character, and this is an invalid xml tag:
<-foo>bar</-foo>
I have checked the official page for maven-bundle-plugin, and they said that it should start with a '-' character as well:
Directives - Any instruction starting with a '-' character is considered to be a directive that informs BND to perform some special processing and is not copied to the manifest.
The bundle goal description doesn't seem to have this information as well.
to perform some special processing and is not copied to the manifest.
Replace the '-' character with '_' character. This will work:
<_foo>bar</_foo>
It is actually vaguely described in the FAQ page:
(this is <_exportcontents> in the POM because a tag can't start with '-')
This improvement also can be found in their issue tracker.
There is an alternative way to define the bnd instructions with less xml clutter:
Configure the plugin like this:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
<_include>-osgi.bnd</_include>
</instructions>
</configuration>
</plugin>
and provide a file (here: osgi.bnd) with the instructions, e.g.
Import-Package: !javax.servlet,\
!org.apache.avalon.framework.logger,\
org.apache.commons.collections;version="[1.0,2)",\
org.apache.commons.collections.comparators;version="[1.0,2)",\
org.apache.commons.collections.keyvalue;version="[1.0,2)",\
org.apache.commons.collections.list;version="[1.0,2)",\
org.apache.commons.collections.set;version="[1.0,2)",\
!org.apache.log,\
!org.apache.log4j,\
*
Export-Package: *
Remark: There is a minus sign in the _include tag before the filename!
A real life example can be found here:
pom.xml file and osgi.bnd file.
Related
I am new to ASCIIDOC and just wanted to know WHERE the following problem comes from.
Setup:
Intellij with the neweset ASCIIDOC-Plugin
neweset asciidoctor-maven-plugin with preserveDirectories = true
I organized my asciidocs like this:
footer.adoc
header.adoc
index.adoc
subfolder
index.adoc
generated-docs looks like this:
footer.html
header.html
index.html
subfolder
index.html
Now, if I want the subfolder/index.html to include header & footer too, I thought I need to write include::../header.adoc[] into the adoc-file which is no problem for the Intellij-Plugin. But in the generated html you will find following error:
<p>Unresolved directive in index.adoc - include::../header.adoc[]</p>
So when I write the following into the adoc-file: include::header.adoc[] the generated html is happy but the Intellij ASCIIDOC plugin shows an error:
Unresolved directive in <stdin> - include::header.adoc[]
I am just wondering if this is a bug for the Intellij Plugin-Team or for the Maven-Plugin-Team. Or maybe someone has a workaround this problem?
And a little bonus question: Is it possible to configure the maven plugin to not generate header-/footer.htmls since they are already included into the actual htmls?
I have no experience with the maven plugin, but I do have lots of experience with AsciiDoc, the IntelliJ Plugin and the Gradle plugin.
The IntelliJ Plugin behaviour is correct. When you convert /subfolder/index.adoc, the includes are resolved relative to this file, so the include include::../header.adoc is correct.
You describe that you don't specify which file to render for the maven plugin (header.adoc is converted). This might be the problem with the maven plugin:
You just specify the source path and all documents are rendered relative to this source path and hence the /subfolder/index.adoc has the wrong source path.
With the Gradle plugin, you cann specify all documents to be converted. This would also avoid getting header.adoc converted. From the maven plugin docs I see that you can specify only a single file.
With this in mind, I would suggest to change your file structure in such a way that you have all the files to be converted in one folder. You can then specify this folder and the other files should not be converted. This also shoul dresolve your problem with the relative path name:
/src/docs/
|
+-common/
| |
| +-header.adoc
| +-footer.adoc
+-chapters/
+-main/
|
+-index1.adoc
+-index2.adoc
I know this is late, the answer is found in the documentation in the restdoc manual from Spring.io in the "Using the Snippets" section of https://spring.io/guides/gs/testing-restdocs/ There is some mention of this in the sample gradle project
The maven plugin configuration should be something like this:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.8</version>
<executions>
<execution>
<id>output-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceHighlighter>coderay</sourceHighlighter>
<backend>html</backend>
<attributes>
<toc/>
<linkcss>false</linkcss>
<snippets>
${project.build.directory}/generated-snippets
</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
I try to generate documentation via Spring Rest Docs using Asciidoctor. User manual says: for highlighting source code in documentation I shall to use :source-highlighter: highlightjs attribute in header of .adoc file.
Here's an example of my index.adoc:
:source-highlighter: highlightjs
= Source code listing
Code listings look cool with Asciidoctor and highlight.js with {highlightjs-theme} theme.
[source,groovy]
----
// File: User.groovy
class User {
String username
}
----
[source,sql]
----
CREATE TABLE USER (
ID INT NOT NULL,
USERNAME VARCHAR(40) NOT NULL
);
----
after that I build and run application, and here's an generated doc without highlighting of source code:
My maven plugin configuration:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-asciidoctor</artifactId>
<version>2.0.2.RELEASE</version>
</dependency>
</dependencies>
</plugin>
What am I doing wrong?
P.S. Also I have tried to install highlight.js locally with renaming highlight/highlight.pack.js to highlight/highlight.min.js and highlight/styles/github.css to highlight/styles/github.min.css and so on, as user manual says but there is no result too
Unfortunately, as you probably figured out, Groovy is not included in the standard highlight.js language pack. It only includes the ones in the "common" section. SQL would work though. As you can see in this picture, the SQL part works with my setup out of the box, but not Groovy.
To fix the Groovy code, you can either use Java as the language (fine for a lot of Groovy code examples) or download the custom HighlightJS pack with Groovy checked. I'm guessing that's where you got to.
If you are using the custom HighlightJS pack, I ran into a similar issue at first. When I went into developer tools in the browser, it showed that the highlight.js files were not found. Another hint that was the problem is that all the Spring REST Docs examples lost their highlighting too. Although the Asciidoctor manual says to put it into the same folder and it should copy over automatically, with Gradle, I still had to tell it to include the highlight files using the resources config option. I'm not a Maven user, but maybe the Maven plugin has a similar setup?
After I fixed the config, it worked for both Groovy and SQL
so I hope that will work for you too.
I am using PDFDoclet with maven-javadoc-plugin and I've come quite a long way with it now. I have the maven and javadoc config almost at a point that is good enough but my immediate problem now is that I can't work out how to push the project version number into the PDF title page.
Before you leap to answer my question by telling me to use maven's <resource> filtering, let me outline why that isn't working.
Filtering works by taking the original file from somewhere in the src folder, doing variable substitution and putting the output in the target folder.
Javadoc works by reading files in src/main/java and src/main/javadoc and AFAIK outputting the results into target. This means filtering is useless for Javadoc since it won't read anything from target
My results show that any maven variables in javadoc comments don't get substituted.
What trick can I use to get those variables substituted into the javadoc?
The solution can't involve filtering the javadoc output after the site:site task, unless resource filtering works on PDFs.
This is the configuration, FWIW:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.3</version>
<configuration>
<show>package</show>
<docfilessubdirs>true</docfilessubdirs>
<tags>
<tag>
<name>pdfInclude</name>
<placement>X</placement>
<head></head>
</tag>
</tags>
</configuration>
<reportSets>
<reportSet>
<id>PDF</id>
<reports>
<report>javadoc</report>
</reports>
<configuration>
<name>PDF</name>
<description>PDF doc</description>
<destDir>pdf</destDir>
<doclet>com.tarsec.javadoc.pdfdoclet.PDFDoclet</doclet>
<docletPath>${basedir}/pdfdoclet/pdfdoclet-1.0.3-all.jar</docletPath>
<useStandardDocletOptions>false</useStandardDocletOptions>
<additionalparam>-pdf my_tech_doc-${project.version}.pdf
-config ${basedir}/pdfdoclet/pdfdoclet.properties</additionalparam>
</configuration>
</reportSet>
</reportSets>
</plugin>
and the pdfdoclet.properties:
# http://pdfdoclet.sourceforge.net/configuration.html
#
#Lets the doclet print additional output in the console and to a logfile.
debug=true
#Print "Author" tags
author=false
#Print "Version" tags
version=true
#Print "since" tags
tag.since=true
#Create summary tables
summary.table=false
#Create hyperlinks
create.links=true
#Encrypt the PDF file
encrypted=false
#Allow printing of the PDF file
allow.printing=true
#Create a bookmark frame
create.frame=true
#Print a title page
api.title.page=true
api.copyright=None
api.author=Hansruedi
#Enables the tag-based filter
filter=true
filter.tags=pdfInclude
font.text.name=resources/arial.ttf
page.orientation=portrait
The PDFDoclet-specific api.* properties should result in a title page as the first page of the PDF, but it doesn't work. If there is a trick that I've missed here and I could get that title page produced, then that might also allow a solution for this somehow.
I realised I can do a quick and dirty hack with the maven <resources> functionality:
<resource>
<directory>${basedir}/src/main/resources</directory>
<targetPath>${basedir}/src/main/javadoc</targetPath>
<filtering>true</filtering>
<includes>
<include>**/overview.html</include>
</includes>
</resource>
This copies my overview.html and filters it, outputting it into the javadoc source directory.
The dirtiness is that this filtered version could then accidentally end up under version control, although using svn I can add it to the ignore list.
Maven assembly plugin adds a suffix to the generated tar.gz which value is value of the <id> when there are more than one descriptor files, like here:
<descriptors>
<descriptor>src/main/assembly/bin-descriptor.xml</descriptor>
<descriptor>src/main/assembly/test-descriptor.xml</descriptor>
</descriptor>
generated files are: project-1.0.0-bin.tar.gz and project-1.0.0-test.tar.gz. When there is only one file in the descriptors, like here:
<descriptors>
<descriptor>src/main/assembly/bin-descriptor.xml</descriptor>
</descriptor>
the output is: project-1.0.0.tar.gz. How to force maven assembly to add a suffix to the name when there is only one file?
It's strange, I'm using Maven 3.0.1 and it also adds the assembly id as a prefix when I use only one descriptor. It's the default behaviour I think.
Try to force it configuring the appendAssemblyId to true.
I'm trying to add custom values in the pom.properties file that Maven generates in the META-INF/maven/${groupId}/${artifactId} location
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.4</version>
<configuration>
<archive>
<manifestEntries>
<build>${BUILD_TAG}</build>
</manifestEntries>
<addMavenDescriptor>true</addMavenDescriptor>
<pomPropertiesFile>${project.build.directory}\interface.properties</pomPropertiesFile>
</archive>
</configuration>
</plugin>
The content of the interface.properties files is
# Build Properties
buildId=746
Using the documentation I have pointed the pomPropertiesFile element to an external properties, but the generated pom.properties file still has the default content after running mvn install
What's the correct usage of the pomPropertiesFile element?
EDIT
I believe that the problem lies in org.apache.maven.archiver.PomPropertiesUtil. If you look at the method sameContents in the source it returns true if the properties in the external file are the same as the defaults and false if different. If the result of sameContents is false, then the contents of the external file are ignored.
Sure enough, this has already been logged as a bug
I think you need to place a file under src/main/resources/META-INF/${groupId}/${artifactId}/interface.properties and let maven do the filtering job (configure the filtering). The file will automatically be copied to target/META-INF/maven/${groupId}/${artifactId}/ location.
See https://issues.apache.org/jira/browse/MNG-4998
Maven 3 will resolve property placeholders eagerly when reading pom.xml for all properties values that are available at this time. Modifying these properties at a later time will not affect the values that are already resolved in pom.xml.
However, if property value is not available (there's no default), then placeholder will not be replaced by the value and it can still be processed later as a placeholder. For example, if a plugin will generate some property during the build, or if placeholder is read and processed by a plugin during some build step.