Processing Documentation

This directory contains PHP scripts responsible for generating the majority of the processing.org website and the Reference documentation included with the Processing software.

Key details:

• Language Reference: Note that the Java language Reference scripts are located in a separate directory: ../java_generate/.
• Local Reference Versions: Files suffixed with local are used to generate alternate versions of pages specifically for the Reference documentation bundled with the Processing software.
• Data Source: The raw data used by these generation scripts is located in the ../content/ directory.

The Processing Development Environment (PDE) uses a keywords.txt file to control syntax highlighting. This file is generated by running the Perl script keywords_create.cgi, which combines the contents of keywords_base.txt with the Reference XML files.

perl keywords_create.cgi

You can control the visibility of contributions in the PDE (Processing Documentation Engine) using two configuration files:

• broken.conf: Add IDs here to mark contributions as broken. They will still appear in the PDE but will be disabled (greyed out).
• skipped.conf: Add IDs here to completely skip contributions. This is typically used to prevent duplicate entries (e.g., skipping a 2.x entry if a 3.x counterpart exists).

Java-generate relies on Javadoc and requires access to the Processing source code. To ensure the tool can locate the necessary files, you must clone both the processing and processing-docs repositories into the same parent directory so they reside side-by-side.

Required directory structure:

• base_dir/processing/
• base_dir/processing-docs/

The documentation is built using a command-line shell script located in the ReferenceGenerator directory.

$ cd ReferenceGenerator/
$ ./processingrefBuild.sh

If you encounter issues importing the Javadoc package or compiling with Ant, you must explicitly tell Java where to find the JDK and libraries by setting the JAVA_HOME environment variable.

On macOS (example for JDK 1.7), add the following to your shell profile (e.g., ~/.bash_profile):

# in e.g. ~/.bash_profile
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_51.jdk/Contents/Home

The sources.conf file maintains a categorized list of contribution properties file URLs. To add a new contribution, follow these steps:

1. Note the current _Next ID_ value at the top of the file.
2. Add the new URL to the appropriate category, prefixing it with the next available ID number.
3. Increment the _Next ID_ value at the top of the file.

Java-generate is compiled using Apache Ant. Ensure you have Ant installed on your machine. If compilation fails, verify that the JDK is installed and the JAVA_HOME environment variable is correctly set to your JDK path.

$ cd ReferenceGenerator/
$ ant compile

Processing 2.x requires data from a contributions.txt file containing only compatible entries. This file must be generated using the build_listing_legacy.py script.

python build_listing_legacy.py

When a method is overloaded, you may want to prevent specific variants from appearing in the generated web documentation. To do this, add the @nowebref Javadoc comment directly above the specific method variant you wish to hide.

/**
  * @nowebref
  */
public void myMethod(int x) { ... }

The build_listing.py script reads sources.conf and generates the contribs.txt file, which contains the processed data for all contributions. You can run the script with varying levels of specificity regarding Processing revisions.

# Basic usage (uses default input/output)
python build_listing.py

# Specify input and output files
python build_listing.py sources.conf contribs.txt

# Filter by compatible Processing revisions (e.g., from 216 to 227)
# Entries out of this range will be skipped
python build_listing.py sources.conf contribs.txt 216 227

# Ignore the upper limit (e.g., from 228 to infinity)
python build_listing.py sources.conf contribs.txt 228 0