The PostScript Reference Guide is a comprehensive, searchable documentation site for the PostScript programming language. It provides detailed reference documentation for PostScript operators, syntax, and usage patterns across all PostScript levels (Level 1, Level 2, and Level 3).
This project is built with Jekyll and the just-the-docs theme to deliver an accessible, well-organized resource for developers, designers, and anyone working with PostScript.
The documentation is deployed at: https://claricle.github.io/postscript-guide/
-
PostScript levels documentation for Level 1, Level 2, and Level 3 specifications
-
Language syntax comprehensive coverage of tokens, objects, operators, procedures, arrays, dictionaries, strings, and data types
-
Operator reference individual pages for 300+ PostScript commands, organized by category
-
Usage guides both basic and advanced tutorials with practical examples
-
Practical examples real-world use cases and code samples
-
Link checking integrated link validation for documentation quality
Build and serve the site locally:
bundle exec jekyll serveOpen your browser to http://localhost:4000/postscript-guide/
To build the static site without serving:
bundle exec jekyll buildThe built site will be in the _site/ directory.
To verify all links in the documentation:
./check-links.shThis script builds the Jekyll site and runs Lychee link checker on the generated HTML. It uses the same configuration as the CI pipeline to ensure consistency.
For more details on link checking, see docs/LINK_CHECKING.md.
postscript-guide/
├── _config.yml # Jekyll configuration
├── Gemfile # Ruby dependencies
├── docs/ # Main documentation
│ ├── index.adoc # Landing page
│ ├── commands/ # Individual command references
│ │ ├── stack-manipulation/
│ │ ├── arithmetic-math/
│ │ ├── array-string/
│ │ ├── dictionary/
│ │ ├── graphics-state/
│ │ ├── path-construction/
│ │ ├── painting/
│ │ ├── transformations/
│ │ ├── font-text/
│ │ ├── color/
│ │ ├── image/
│ │ ├── device-output/
│ │ ├── file-io/
│ │ ├── control-flow/
│ │ ├── resource-management/
│ │ └── error-handling/
│ ├── levels/ # PostScript version documentation
│ ├── syntax/ # Language syntax guides
│ ├── usage/ # Usage tutorials
│ │ ├── basic/
│ │ └── advanced/
│ ├── examples/ # Practical examples
│ └── glossary.adoc # Terminology referenceAll documentation is written in AsciiDoc format (.adoc files) for better
technical documentation support. The Jekyll AsciiDoc plugin converts these to
HTML during the build process.
Each PostScript command follows a consistent structure to ensure comprehensive coverage and ease of use.
- Description
-
What the command does and when to use it
- Syntax
-
Stack effect notation showing before/after states
- Parameters
-
Detailed parameter descriptions
- Examples
-
Basic and advanced usage examples
- Edge cases
-
Common pitfalls and warnings
- Related commands
-
Cross-references to related operators
- Error conditions
-
Possible errors and their causes
= dup
== Description
Duplicates the top element on the operand stack.
== Syntax
[source,postscript]any dup any any
== Parameters any:: Any object type == Examples === Basic usage [source,postscript]
5 dup % Stack: 5 5
=== Advanced usage [source,postscript]
/myname dup length % Stack: /myname 6
== Related commands * link:pop.adoc[pop] - Remove top element * link:exch.adoc[exch] - Exchange top two elements
Contributions are welcome! Here’s how you can help improve the PostScript Reference Guide.
-
Use the GitHub Issues page
-
Provide clear descriptions of errors or missing content
-
Include specific examples when possible
-
Fork the repository
-
Create a feature branch (
git checkout -b feature/improve-documentation) -
Make your changes following the existing format
-
Test locally with
bundle exec jekyll serve -
Commit with clear messages (
git commit -am 'Add missing example for arc operator') -
Push to your fork (
git push origin feature/improve-documentation) -
Open a Pull Request
-
Use AsciiDoc format for all documentation
-
Follow the established template structure for command pages
-
Include practical, tested examples
-
Add cross-references to related commands
-
Keep descriptions clear and concise
-
Use consistent terminology from the glossary
-
Ensure line wrap at 80 characters except for cross-references and formulas
-
Apply MECE (Mutually Exclusive, Collectively Exhaustive) principles to documentation structure
When documenting a command, ensure:
-
❏ Clear, accurate description
-
❏ Complete stack effect notation
-
❏ All parameters documented
-
❏ At least one basic example
-
❏ Advanced example when applicable
-
❏ Common pitfalls noted
-
❏ Related commands cross-referenced
-
❏ Error conditions listed
-
❏ PostScript level specified
This documentation is based on:
-
Adobe PostScript Reference Manual (PLRM)
-
PostScript Language Tutorial and Cookbook
-
Community contributions and corrections
This project is licensed under the MIT License - see the LICENSE file for details.
-
Adobe Systems for the PostScript language specification
-
The just-the-docs theme maintainers
-
Contributors to the PostScript documentation community