This wiki is a place to create Windup documentation in a collaborative manner, a bit wildly, and on the fly. It is intended to reflect the state of the Windup source code master branch, however pages may become obsolete as the master changes quickly.

The Wiki pages are divided into the following main areas of interest, which may often overlap. The page names use these prefixes:

• Dev-: …​: These pages are of interest to Windup core developers.

• Rules- …​: These pages are of interest to rules developers.

• User- …​: These pages that are of interest to Windup users.

• no prefix: These pages that are also of interest to all users.

This Wiki uses AsciiDoc because it is capable of handling the publishing requirements and structural elements needed to create technical books. If you would like to contribute to the documentation, feel free to use your favorite Wiki language, however, it will ultimately be converted to AsciiDoc.

Please see the Contributing Guidelines for details about how to name pages and use the correct AsciiDoc syntax to make the transition to the final documentation go more smoothly.

The following is a brief overview.

• Name wiki pages using only letters, numbers and dashes. Do not include spaces, colons, or other special characters in page names.

• Always use the ProductName or ProductShortName variables when referring to the product name.

• Do not use the product name in page names or in headers. This is because you should always use the variables when referring to the product names and the variables do not work in generated anchors.

• Use the following variables instead of hard-coded values

  {ProductName} - The full product name
  {ProductShortName} - The abbreviated product name
  {ProductVersion} - The current product version
  {ProductDistribution} - The distribution file name
  {ProductHomeVar} - The installation home variable
  {ProductSrcHomeVar} - The source home variable
  {ProductReleaseVar} - The product release variable

• Be sure to add a level 3 page heading (===) at the top of each page. When compiled in a book, the Guide name is the top level, chapters are level 2, and the page is level 3. This is the title that appears in the table of contents for the page.

  === Review the Quickstarts

• At the beginning of each new Wiki page, add an anchor with the exact page name, including the dashes. This generates the correct anchors that are needed when the pages are combined into a book.

  [[Page-Name]]
  === Page Name

• When creating code blocks, use 4 dashes ("----") to begin and end it, and add the "[options="nowrap"]" directive preceding the block, otherwise the code will wrap when the HTML is created.

  [options="nowrap"]
  ----
  code goes here...
  ----

• Wiki generates anchors using dashes for spaces. AsciiDoctor generates a leading underscore and underscores for spaces. When referring to another section within the same page, do not use the <<section-title-anchor>> syntax. Instead, create an anchor and use the 'xref:' syntax to provide the link. Replace spaces in the section title with dashes.

  • Create the anchor at the top of the section using double brackets to force the generation of dashes instead of underscores.

    [[section-header]]
    ==== Section Header

  • Then use the xref to create the link within the page.

    See xref:section-header[Section Header] for more information.

  • To create a link to a section within another page, first create the section anchor in the other page, then create the reference.

    Anchor within Execute page

    [[start-windup]]
    ==== Start {ProductShortName}

    Reference from Rules-Create-a-Basic-Java-based-Rule-Add-on page:

    link:Execute#start-windup[Start {ProductShortName}].

• In Asciidoctor 1.5.0, the backtick is no longer an inline monospaced literal. This means that the wildcard character (*) within backticks renders as an emphasis tag, resulting in the following build error.

  parser error : Opening and ending tag mismatch

  Wildcard characters (*) within tick marks must be preceded by [x-], for example"

  [x-]`org.apache.commons.{*}`

  This is described in further detail here: https://github.com/asciidoctor/asciidoctor/issues/1045