Rework site documentation

* fix wording and typos * enable syntax highlighting * enable line numbers for code blocks * replace tabs in code blocks for unified layout * upgrade skin (dependabot doesn't work for site.xml)
eclipse-tycho · Dec 27, 2024 · ca21995 · ca21995
1 parent 3172e56
commit ca21995
Show file tree

Hide file tree

Showing 11 changed files with 227 additions and 226 deletions.
diff --git a/src/site/markdown/BndBuild.md b/src/site/markdown/BndBuild.md
@@ -1,11 +1,11 @@
 # BND Workspace Layout and Pomless Builds
 
-Tycho supports building projects that use the **BND Workspace Layout** as [described here](https://bndtools.org/concepts.html).
+Tycho supports building projects that use the [BND Workspace Layout](https://bndtools.org/concepts.html).
 
 ## BND Workspace Layout
 A BND Workspace layout build layout usually has the following structure:
 
-- `root folder` - this usually is the root of your project repository (e.g. git)
+- `root folder` - this usually is the root of your project repository
     - `cnf` - configuration folder for general setup
         - `build.bnd` - main configuration file
         - `ext` - additional configuration (optional)
@@ -15,37 +15,34 @@ A BND Workspace layout build layout usually has the following structure:
         - `bnd.bnd` - project configuration file
     - `...`
 
-any folder that do not match the layout is ignored.
+Any folder that does not match the layout is ignored.
 
 ## Pomless Builds
 Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
-In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most all from your supplied bnd configuration files, so everything is configured there and usually no additional maven configuration is required, therefore this build is completely pomless (no pom.xml), there are only a few steps to consider:
+In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most all from your supplied bnd configuration files, so everything is configured there and usually no additional maven configuration is required, therefore this build is completely pomless (no `pom.xml`), there are only a few steps to consider:
 
-1. Add a folder called `.mvn` to the root
-2. Inside the `.mvn` folder place a file called `extensions.xml` with the following content:
-
-```
+- Add a folder called `.mvn` to the root
+- Inside the `.mvn` folder place a file called `extensions.xml` with the following content:
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <extensions>
-  <extension>
-    <groupId>org.eclipse.tycho</groupId>
-    <artifactId>tycho-build</artifactId>
-    <version>${tycho-version}</version>
-  </extension>
+   <extension>
+      <groupId>org.eclipse.tycho</groupId>
+      <artifactId>tycho-build</artifactId>
+      <version>${tycho-version}</version>
+   </extension>
 </extensions>
 ```
 
-3. create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):
-
+- create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):
+```properties
+-Dtycho-version=4.0.10
 ```
--Dtycho-version=3.0.0
-```
-4. You can now run your build with `mvn clean verify`
 
-A runnable demo can be found here:
-https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-workspace
+- You can now run your build with `mvn clean verify`.
+
+You can check more details in a [demo project](https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-workspace).
 
 ## Mixed Builds
 
-You can even combine a BND Workspace and PDE bundles in a build, a runnable demo can be found here:
-https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-pde-workspace
+You can even combine a BND Workspace and PDE bundles in a build, see [demo](https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-pde-workspace).
diff --git a/src/site/markdown/BuildProperties.md b/src/site/markdown/BuildProperties.md
@@ -2,16 +2,16 @@
 
 Tycho uses the `build.properties` file [as defined by PDE](https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.pde.doc.user/reference/pde_feature_generating_build.htm) to configure various aspects of the build.
 
-Note that Tycho only supports a subset of keys defined by PDE. 
+Note that Tycho only supports a subset of keys defined by PDE.
 If a key is not supported, this may be because:
 
 * it's legacy/deprecated
 * it doesn't fit into the maven project model or the way maven is generally expected to work
 * there are other ways to achieve the desired configuration (e.g. using pom.xml)
 * it's a missing feature
 
-In additional to the PDE properties, Tycho supports property expressions like `${project.version}` in `build.properties` values. 
-These expressions are only used in a Tycho build, not when using the Eclipse IDE incremental build.  
+In additional to the PDE properties, Tycho supports property expressions like `${project.version}` in `build.properties` values.
+These expressions are only used in a Tycho build, not when using the Eclipse IDE incremental build.
 
 See the table below for which keys in `build.properties` defined by PDE are supported by Tycho or if not, whether there are alternatives when using Tycho.
 
@@ -21,7 +21,7 @@ Key | Value
 --- | ---
 bin.includes | supported
 bin.excludes | supported
-qualifier    | not supported - use [Build Qualifer Mojo](tycho-packaging-plugin/build-qualifier-mojo.html) instead
+qualifier    | not supported - use [Build Qualifier Mojo](tycho-packaging-plugin/build-qualifier-mojo.html) instead
 forceContextQualifier | supported
 custom*      | not supported
 
@@ -38,7 +38,7 @@ src.includes | supported
 src.excludes | supported
 jars.extra.classpath | only supported in the form `platform:/plugin/<Bundle-SymbolicName>[/path/to/nested/jar]`
 jars.compile.order | supported
-additional.bundles | supported (since Tycho 2.4.0)
+additional.bundles | supported
 
 
 ## Compiler-specific properties
@@ -53,7 +53,7 @@ javacWarnings.library | not supported - use [compilerArgument](https://wiki.ecli
 javacErrors.library | not supported - use [compilerArgument](https://wiki.eclipse.org/Tycho/FAQ#How_to_configure_warning.2Ferror_settings_of_the_OSGi_compiler.3F) instead.
 javacDefaultEncoding.library | supported
 javacCustomEncodings.library | not supported
-javacProjectSettings | not supported. Use [useProjectSettings](tycho-compiler-plugin/compile-mojo.html#useProjectSettings) or [compilerArgs](tycho-compiler-plugin/compile-mojo.html#compilerArgs) instead. 
+javacProjectSettings | not supported. Use [useProjectSettings](tycho-compiler-plugin/compile-mojo.html#useProjectSettings) or [compilerArgs](tycho-compiler-plugin/compile-mojo.html#compilerArgs) instead.
 compilerArg | not supported. Use [compilerArgs](tycho-compiler-plugin/compile-mojo.html#compilerArgs) instead
 compilerAdapter | not supported. Use [compilerId](tycho-compiler-plugin/compile-mojo.html#compilerId) instead
 compilerAdapter.useLog | not supported
@@ -66,8 +66,8 @@ Key | Value
 --- | ---
 root | supported
 root.config | supported
-root.folder | supported (since Tycho 0.27.0)
-root.config.folder | supported (since Tycho 0.27.0)
+root.folder | supported
+root.config.folder | supported
 root.permissions | supported
 root.link | supported
 generate.feature | not supported - use [Tycho Source Plugin](tycho-source-plugin/plugin-info.html) instead

diff --git a/src/site/markdown/Category.md b/src/site/markdown/Category.md
@@ -1,16 +1,15 @@
 # Category
 
-A category.xml file can be used to define which content is placed into a p2 repository. 
-It can also specify how to display the content in the p2 installation dialog. 
+A `category.xml` file can be used to define which content is placed into a p2 repository.
+It can also specify how to display the content in the p2 installation dialog.
 For Tycho to use it, it must to be placed into the root of an project with the packaging type 'eclipse-repository'.
 
-The 'category.xml' format was originally defined by the Eclipse PDE project. 
+The `category.xml` format was originally defined by the Eclipse PDE project.
 There are extensions to the format only supported by p2 and Tycho.
 
-The following listing is a simple category file listing only one feature and one plug-in.
+The following snippet is a simple category file listing only one feature and one plug-in.
 
-
-```
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <site>
    <feature id="com.example.feature">
@@ -19,26 +18,27 @@ The following listing is a simple category file listing only one feature and one
    <category-def name="com.example.category.update" label="Example update site"/>
 </site>
 ```
+
 The following is an example, demonstrating a complex category definition.
 
-```
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <site>
    <!-- Include features -->
    <feature id="feature.id" version="1.4.100.v2009"/>
    <!-- Since Tycho 1.1.0 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=407273#c18), features can declare platform-specific compatibility for multi-platform builds -->
    <!-- Examples: https://github.com/mickaelistria/org.eclipse.simrel.build/blob/master/categories/category.xml#L581 -->
    <feature id="linux.specific.feature.id" version="0.0.0" os="linux"/>
- 
+
    <!-- Directly include bundles, without a feature -->
    <bundle id="bundle.id" version="1.3.1.v2023"/>
-   
+
    <!-- Directly include any iu -->
    <iu id="unit.id"/>
-   
+
    <!-- Include all IUs matching an expression -->
    <iu>
-     <query> 
+     <query>
        <expression type="match">
          <![CDATA[
            id == $0
@@ -47,21 +47,21 @@ The following is an example, demonstrating a complex category definition.
        <param>another.unit.id</param>
      </query>
    </iu>
- 
+
    <!-- Categories -->
    <feature id="feature.in.category">
       <category name="category.id"/>
    </feature>
    <category-def name="category.id" label="Category Label">
       <description>Details on the category</description>
    </category-def>
- 
+
    <!-- example for a dynamic category -->
    <category-def name="javax" label="Bundles starting with javax."/>
    <iu>
       <category name="javax"/>
       <query>
-      	<expression type="match">id ~= /javax.*/</expression>
+         <expression type="match">id ~= /javax.*/</expression>
       </query>
    </iu>
 </site>

diff --git a/src/site/markdown/PackagingTypes.md b/src/site/markdown/PackagingTypes.md
@@ -3,20 +3,20 @@
 Tycho defines the following custom Maven packaging types targeted for Eclipse Plug-in development.
 
 * `eclipse-plugin` corresponds to [Eclipse Plug-in and Plug-in Fragment projects](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Plug-in).
-* `eclipse-test-plugin` is similar to `eclipse-plugin` but only contains Plugin Tests to be executed inside an OSGi runtime. There is a noticable difference between `eclipse-plugin` and `eclipse-test-plugin` with respect to the goal executed during `integration-test`. The former uses `tycho-surefire-plugin:integration-test` while the latter uses `tycho-surefire-plugin:test`.
+* `eclipse-test-plugin` is similar to `eclipse-plugin` but only contains Plugin Tests to be executed inside an OSGi runtime. There is a notable difference between `eclipse-plugin` and `eclipse-test-plugin` with respect to the goal executed during `integration-test`. The former uses `tycho-surefire-plugin:integration-test` while the latter uses `tycho-surefire-plugin:test`.
 * `eclipse-feature` corresponds to [Eclipse Feature projects](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Feature)
-* `eclipse-repository` corresponds to projects containing a `category.xml` file, the support of [Eclipse Update Site projects]https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Update-Site) has been removed in latest Tycho versions
+* `eclipse-repository` corresponds to projects containing a `category.xml` file, the support of [Eclipse Update Site projects](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Update-Site) has been removed in latest Tycho versions
 * `eclipse-target-definition` corresponds to [Eclipse Target Platform](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Target_Platform)
 * `p2-installable-unit` corresponds to [Installable Units](https://github.com/eclipse-equinox/p2/blob/master/docs/Installable_Units.md)
 
 The lifecycle bindings (i.e. which Maven plugins are executed in which Maven phase by default) are defined by `tycho-maven-plugin` in a [Maven extension](https://maven.apache.org/guides/mini/guide-using-extensions.html) therefore it needs to be loaded accordingly:
 
-```
+```xml
 <plugin>
-  <groupId>org.apache.tycho</groupId>
-  <artifactId>tycho-maven-plugin</artifactId>
-  <version>${project.version}</version>
-  <extensions>true</extensions>
+   <groupId>org.apache.tycho</groupId>
+   <artifactId>tycho-maven-plugin</artifactId>
+   <version>${project.version}</version>
+   <extensions>true</extensions>
 </plugin>
 ```
 
@@ -25,11 +25,11 @@ Only the `default` lifecycle has custom bindings, i.e. the [`clean` and `site` l
 
 The according artifact handlers (i.e. the mapping from the packaging type to a specific extension) are provided by `p2-maven-plugin` in <https://github.com/eclipse-tycho/tycho/tree/master/p2-maven-plugin/src/main/java/org/eclipse/tycho/p2maven/repository>. When referencing one of the packaging types as Maven dependency it needs to be loaded with extensions as well:
 
-```
+```xml
 <plugin>
-  <groupId>org.apache.tycho</groupId>
-  <artifactId>p2-maven-plugin</artifactId>
-  <version>${project.version}</version>
-  <extensions>true</extensions>
+   <groupId>org.apache.tycho</groupId>
+   <artifactId>p2-maven-plugin</artifactId>
+   <version>${project.version}</version>
+   <extensions>true</extensions>
 </plugin>
 ```
diff --git a/src/site/markdown/StructuredBuild.md b/src/site/markdown/StructuredBuild.md
@@ -1,9 +1,9 @@
 # Structured Build Layout and Pomless Builds
 
-Tycho supports any layout of your build, but you can save you a lot of configuration work if you are using the so called **Structured Build Layout**.
+Tycho supports any layout of your build, but you can save a lot of configuration effort if you use the so called **Structured Build Layout**.
 
 ## Structured Build Layout
-A structured build layout usually has the following folder layout, even though you might not use all of the depending on your project:
+A structured build layout usually has the following folders, even though you might not use all of them depending on your project:
 
 - `root folder` - this usually contains your parent pom where you configure the plugins to use
     - `bundles` (or `plugins`) - this contains your bundles that make up your application
@@ -23,71 +23,68 @@ A structured build layout usually has the following folder layout, even though y
 
 ## Pomless Builds
 Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
-In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most if not all from your existing data, that is the files you are created and using in our IDE, 
-there are only a few steps to consider:
+In a traditional Maven build each module has to contain a `pom.xml` file.
+Tycho however can derive most of the information from other already existing files, if your project follows the above structured build layout.
 
-1. Add a folder called `.mvn` to the root
-2. Inside the `.mvn` folder place a file called `extensions.xml` with the following content:
-
-```
+- Add a folder called `.mvn` to the root
+- Inside the `.mvn` folder place a file called `extensions.xml` with the following content:
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <extensions>
-  <extension>
-    <groupId>org.eclipse.tycho</groupId>
-    <artifactId>tycho-build</artifactId>
-    <version>${tycho-version}</version>
-  </extension>
+   <extension>
+      <groupId>org.eclipse.tycho</groupId>
+      <artifactId>tycho-build</artifactId>
+      <version>${tycho-version}</version>
+   </extension>
 </extensions>
 ```
 
-3. create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):
-
-```
--Dtycho-version=3.0.0
+- Create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):
+```properties
+-Dtycho-version=4.0.10
 ```
 
-4. finally create a `pom.xml` with the following content in the root folder:
-
-```
+- Finally create a `pom.xml` with the following content in the root folder:
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <project
-	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
-	xmlns="http://maven.apache.org/POM/4.0.0"
-	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-	<modelVersion>4.0.0</modelVersion>
-	<groupId> ... your desired group id ...</groupId>
-	<artifactId>parent</artifactId>
-	<version>1.0.0-SNAPSHOT</version>
-	<packaging>pom</packaging>
-	
-	<modules>
-		<module>bundles</module>
-		<module>features</module>
-		<module>sites</module>
-		<module>products</module>
-	</modules>
-	
-	<build>
-		<plugins>
-			<plugin>
-				<groupId>org.eclipse.tycho</groupId>
-				<artifactId>tycho-maven-plugin</artifactId>
-				<version>${tycho-version}</version>
-				<extensions>true</extensions>
-			</plugin>
-			<plugin>
-				<groupId>org.eclipse.tycho</groupId>
-				<artifactId>target-platform-configuration</artifactId>
-				<version>${tycho-version}</version>
-				<configuration>
-					<target>
-						<file>../../target-platform.target</file>
-					</target>
-				</configuration>
-			</plugin>
-		</plugins>
-	</build>
+   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
+   xmlns="http://maven.apache.org/POM/4.0.0"
+   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+   <modelVersion>4.0.0</modelVersion>
+   <groupId> ... your desired group id ...</groupId>
+   <artifactId>parent</artifactId>
+   <version>1.0.0-SNAPSHOT</version>
+   <packaging>pom</packaging>
+
+   <modules>
+      <module>bundles</module>
+      <module>features</module>
+      <module>sites</module>
+      <module>products</module>
+   </modules>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.eclipse.tycho</groupId>
+            <artifactId>tycho-maven-plugin</artifactId>
+            <version>${tycho-version}</version>
+            <extensions>true</extensions>
+         </plugin>
+         <plugin>
+            <groupId>org.eclipse.tycho</groupId>
+            <artifactId>target-platform-configuration</artifactId>
+            <version>${tycho-version}</version>
+            <configuration>
+               <target>
+                  <file>../../target-platform.target</file>
+               </target>
+            </configuration>
+         </plugin>
+      </plugins>
+   </build>
 </project>
 ```
 
-5. You can now run your build with `mvn clean verify`
+- You can now run your build with `mvn verify`.
diff --git a/src/site/markdown/SystemProperties.md b/src/site/markdown/SystemProperties.md
@@ -34,7 +34,7 @@ These properties control the behavior of P2 used by Tycho
 Name | Value | Default | Documentation
 --- | --- | --- | ---
 eclipse.p2.mirrors | true / false | true | Each p2 site can define a list of artifact repository mirrors, this controls if P2 mirrors should be used. This is independent from configuring mirrors in the maven configuration to be used by Tycho!
-eclipse.p2.maxDownloadAttempts | _any positive integer_ | 3 | Describes how often Tycho attempts to re-download an artifact from a p2 repository in case e.g. a bad mirror was used. One can think of this value as the maximum number of mirrors Tycho/p2 will check. 
+eclipse.p2.maxDownloadAttempts | _any positive integer_ | 3 | Describes how often Tycho attempts to re-download an artifact from a p2 repository in case e.g. a bad mirror was used. One can think of this value as the maximum number of mirrors Tycho/p2 will check.
 
 ### Tycho P2 Transport