Initial commit

docs/modules/introduction/pages/comparison.adoc

@@ -0,0 +1,93 @@
+= Comparison
+include::ROOT:partial$component-attributes.adoc[]
+:uri-jsonnet: https://jsonnet.org
+:uri-hcl: https://github.com/hashicorp/hcl
+:uri-dhall: https://dhall-lang.org
+:uri-pkl-spring: https://github.com/apple/pkl-spring
+:uri-graalvm: https://www.graalvm.org
+
+Configuration is often described in a static configuration format or is generated with a general-purpose programming language.
+This page lists shortcomings of these approaches and explains how Pkl addresses them.
+Also, Pkl's strong and weak points in comparison to other configuration languages are discussed in this document.
+
+[[static-config-formats]]
+== Pkl vs. Static Config Formats
+
+Static configuration formats such as JSON, YAML, and XML work reasonably well for simple configuration needs.
+However, they do have some shortcomings, including:
+
+. They are not very human-friendly to read and write. (JSON, XML)
+. They do not provide a way to split a large file into multiple smaller ones. (JSON, YAML)
+. They offer no way or very limited ways to abstract over repetitive configuration. (JSON, YAML, XML)
+. They do not offer standardized or widely available schema validators. (JSON, YAML)
+. They offer little or no schema-aware tooling. (JSON, YAML)
+
+Pkl addresses these shortcomings as follows:
+
+. It has a clutter-free and familiar syntax with nestable comments.
+. Modules can import other modules from local and remote locations.
+. Every object can act as a template for other objects.
+  The standard library offers strong support for data manipulation.
+. It has strong built-in support for describing and validating configuration schemas.
+. It is designed to enable schema-aware tooling, such as REPLs and editors with code completion support.
+
+[[general-purpose-langs]]
+== Pkl vs. General-purpose Languages
+
+When configuration needs outgrow the capabilities of static configuration formats,
+projects often turn to generate configuration with a general-purpose programming language such as Python.
+Given enough effort, this approach can satisfy complex configuration needs.
+However, expressing configuration in a full-blown programming language does have some shortcomings, including:
+
+. Reading, writing, and debugging configuration can become as challenging as reading, writing, and debugging application code.
+. The host language may not be a good fit for describing, manipulating, and abstracting over hierarchical configuration.
+. Configuration code may not visually resemble the configuration it generates.
+. The host language may not be a good fit for defining and validating configuration schemas.
+. Development environments may offer little help for developing and validating configuration written in the host language.
+. General-purpose languages are powerful and often difficult to sandbox.
+  Are you certain your configuration script isn't erasing your hard disk or launching a rocket?
+
+Pkl addresses these shortcomings as follows:
+
+. As an expression-oriented and side-effect free language, it eliminates many potential sources of errors.
+. It is specifically designed for describing, manipulating, and abstracting over hierarchical configuration.
+. Pkl code often resembles the configuration it generates.
+. It has strong built-in support for defining and validating configuration schemas.
+. It is designed to enable advanced and schema-aware tooling.
+. It is comparatively powerless and strictly sandboxed, making fatal configuration mistakes and exploits less likely.
+  Till now, we haven't spotted any Pkl script capable of erasing your hard disk.
+
+[[other-config-langs]]
+== Pkl vs. Other Config Languages
+
+Compared to open-source configuration languages such as link:{uri-jsonnet}[Jsonnet],
+link:{uri-hcl}[HCL], and link:{uri-dhall}[Dhall], Pkl's strong points are:
+
+General::
++
+* Pkl has a clean and familiar syntax, which makes it easier to read and learn.
+* Pkl supports writing sophisticated schemas, which enables config validation, code and documentation generation, and advanced IDE support.
+  This is Pkl's most significant differentiator, and is the main reason why we created it.
+* Pkl has stronger templating capabilities than other config languages, reducing user code to the absolute minimum.
+
+Embedding::
++
+* Pkl is great for embedding into JVM applications.
+* Pkl offers modern xref:java-binding:pkl-config-java.adoc[JVM libraries] for runtime application configuration.
+* Pkl supports xref:java-binding:codegen.adoc[code generation] to enable statically typed access to configuration from programming languages.
+* Pkl integrates with third-party (link:{uri-pkl-spring}[Spring Boot]) JVM libraries and frameworks.
+
+Tooling::
++
+* Pkl has a polished xref:pkl-doc:index.adoc[documentation generator] that produces highly navigable and searchable documentation.
+* Pkl offers a xref:pkl-gradle:index.adoc[Gradle plugin] to easily integrate code evaluation, documentation generation, and code generation into your builds.
+* Pkl's native executables have a link:{uri-graalvm}[JIT compiler] that can speed up evaluation up to hundred times.
+
+On the other hand, we believe that Pkl's weak points are:
+
+* Pkl's native binaries are larger than those of other config languages.
+* Pkl is less known and has a smaller community than some other config languages.
+
+We are working towards making Pkl overcome these weakness. Please support us in reaching this goal!
+
+We hope that you will enjoy Pkl, and that you trust us to gradually improve its weak points.

docs/modules/introduction/pages/concepts.adoc

@@ -0,0 +1,97 @@
+= Concepts
+include::ROOT:partial$component-attributes.adoc[]
+:uri-property-list: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html
+
+Let's get to know Pkl by discussing some of its concepts and features.
+
+[[abstraction]]
+== Abstraction
+
+Configuration tends to grow larger and more complex over time, making it increasingly difficult to understand and maintain.
+Pkl can reduce the size and complexity of configuration by
+
+* describing similar configuration elements in terms of their differences
+* introducing abstractions for common configuration elements
+* separating configuration structure from configuration data
+* computing instead of enumerating configuration
+
+[[evaluation]]
+== Evaluation
+
+Pkl code lives in _modules_, a more fancy and general term for _files_.
+Evaluating a module produces an in-memory _data model_ that is roughly comparable to a JSON data model.
+If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation and terminates with the status code zero.
+Otherwise, the evaluator prints an error message and terminates with a non-zero status code.
+
+[[immutability]]
+== Immutability
+
+All Pkl data is immutable.
+Manipulating a value always returns a new value, leaving the original value unchanged.
+Immutability eliminates many potential sources of errors.
+
+[[isolation]]
+== Isolation
+
+Evaluation of Pkl code is strictly sandboxed.
+Except for a few well-defined and well-controlled exceptions, Pkl code cannot interact with the outside world.
+Leaving aside bugs in the language implementation, the worst thing that buggy or malicious Pkl code can do is to consume CPU and memory resources until the evaluator gets killed.
+Over time, sandboxing will be further strengthened to cover fine-grained CPU and memory boxing.
+
+[[rendering]]
+== Rendering
+
+Converting a data model to an external representation is called _rendering_ the model.
+Pkl ships with renderers for the following data formats:
+
+* JSON
+* Jsonnet
+* Pcf (a static subset of Pkl)
+* (Java) Properties
+* {uri-property-list}[Property List]
+* XML
+* YAML
+
+Support for other formats can be added by writing a custom renderer in Pkl or Java.
+See xref:language-reference:index.adoc#module-output[Module Output] and xref:pkl-core:index.adoc#value-visitor[Value Visitor] for more information.
+
+[[resemblance]]
+== Resemblance
+
+By design, Pkl code tends to structurally and visually resemble the configuration it generates.
+This makes the code easier to read and write.
+
+[[reuse]]
+== Reuse
+
+Modules can reuse other modules by xref:language-reference:index.adoc#import-module[importing] them from local or remote locations.
+Imports can also be used to split up one large module into multiple smaller ones, increasing maintainability.
+A configurable security policy helps to keep imports under control.
+
+[[schema]]
+== Schema
+
+Configuration is structured data.
+Pkl supports -- but does not require -- to express this structure as a _configuration schema_, a set of classes defining configuration properties, their defaults, types, and constraints.
+Writing and maintaining a configuration schema takes some effort but, in return, provides these benefits:
+
+* Independent evolution of configuration schema and configuration data, often by different teams (for example service providers and service consumers).
+* Automatic xref:pkl-doc:index.adoc[documentation generation].
+* Strong validation of configuration, both during development time and runtime.
+* Statically typed access to configuration from xref:java-binding:codegen.adoc[Java] and other languages through code generation.
+* Schema-aware development tools, for example REPLs and editors with code completion support.
+
+[[template]]
+== Templating
+
+Pkl supports writing templates for objects and entire modules.
+Templates can be repeatedly turned into concrete configuration by filling in the blanks, and -- when necessary -- overriding defaults.
+Sharing template modules over the network can streamline complex configuration tasks for entire teams, organizations, and communities.
+
+[[usability]]
+== Usability
+
+Everybody needs a configuration solution, but nobody wants to spend a lot of time learning it.
+To reflect this reality, Pkl has a strong focus on usability.
+For example, error messages explain causes and possible solutions and object properties maintain definition order to avoid surprises.
+We hope that this focus on usability will make Pkl accessible to a wide audience of occasional users, while still leaving room for expert users and advanced use cases.

docs/modules/introduction/pages/index.adoc

@@ -0,0 +1,13 @@
+= Introduction
+include::ROOT:partial$component-attributes.adoc[]
+
+Pkl -- pronounced _Pickle_ -- is a configuration-as-code language with rich validation and tooling.
+It can be used as a command line tool, software library, or build plugin.
+Pkl scales from small to large, simple to complex, ad-hoc to recurring configuration tasks.
+
+We created Pkl because we believe that configuration is best expressed in a special-purpose configuration language;
+a blend between a static configuration format, and a general-purpose programming language.
+
+* xref:use-cases.adoc[Use Cases]
+* xref:concepts.adoc[Concepts]
+* xref:comparison.adoc[Comparison]

docs/modules/introduction/pages/use-cases.adoc

@@ -0,0 +1,35 @@
+= Use Cases
+include::ROOT:partial$component-attributes.adoc[]
+:uri-kotlin-homepage: https://kotlinlang.org
+:uri-xml-property-lists: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html
+
+Pkl is a good fit for:
+
+Generating Static Configuration::
+Are you using a tool, service, or application that is configured with JSON, YAML, or any other static configuration format?
++
+By generating this configuration with Pkl, you can reduce verbosity and increase maintainability through xref:concepts.adoc#reuse[reuse], xref:concepts.adoc#template[templating], and xref:concepts.adoc#abstraction[abstraction].
+JSON, YAML, and {uri-xml-property-lists}[XML property lists] are supported out of the box; xref:concepts.adoc#rendering[renderers] for other configuration formats can be developed and shared by anyone.
+Automatic defaults, strong validation, and sensible error messages come in reach with configuration xref:concepts.adoc#schema[schemas].
++
+Generation can be triggered manually, by an automation pipeline, or by the target application.
+
+Application Runtime Configuration::
+Are you the author of a tool, service, or application that consumes configuration?
++
+By adopting Pkl as your "native" configuration solution (rather than, say, using it to generate JSON files), you benefit from a modern xref:java-binding:pkl-config-java.adoc[configuration library] that is safe, easy, and enjoyable to use.
+At the same time, anyone configuring your application -- whether that's your users, site reliability engineers (SREs), or yourself -- benefit from a well-defined, well-documented, and scalable configuration language.
++
+At the time of writing, Pkl offers configuration libraries for the JVM runtime, Swift, and also for Golang.
++
+We maintian the following libraries:
++
+* xref:java-binding:pkl-config-java.adoc[pkl-config-java] for Java compatible languages
+* xref:kotlin-binding:pkl-config-kotlin.adoc[pkl-config-kotlin] for the {uri-kotlin-homepage}[Kotlin] language.
+* xref:swift:ROOT:index.adoc[pkl-swift] for the Swift language.
+* xref:go:ROOT:index.adoc[pkl-go] for the Go language.
+
+In the future, we hope to add support for other popular languages and platforms, realizing our vision of a polyglot config solution based on a single config language.
+
+<Your Use Case Here>::
+We are just getting started. Tell us about _your_ Pkl success story!