translating more docs

docs/docs/api.surface.mdx

@@ -19,9 +19,9 @@ ___
 <RoleAlignments />
 
 export const toc = [
-  AlignmentMarkerToc,
-  AlignmentToc,
-  RoleAlignmentToc,
-  AlignmentsToc,
-  RoleAlignmentsToc,
+  ...AlignmentMarkerToc,
+  ...AlignmentToc,
+  ...RoleAlignmentToc,
+  ...AlignmentsToc,
+  ...RoleAlignmentsToc,
 ];

docs/docs/intro.md

@@ -1,5 +1,4 @@
 ---
-sidebar_position: 1
 slug: /
 ---
 
@@ -8,20 +7,33 @@ slug: /
 [![ci](https://img.shields.io/github/actions/workflow/status/chanind/penman-js/ci.yaml?branch=main)](https://github.com/chanind/penman-js)
 [![Npm](https://img.shields.io/npm/v/penman-js)](https://www.npmjs.com/package/penman-js)
 
-PENMAN notation (e.g. AMR) parser and generator for JavaScript
+Abstract Meaning Representation (AMR) parser and generator for JavaScript.
 
 ## About
 
-This library is a manual port of the Penman Python library, with identical method names and import structure. However, as Python and Javascript do have some differences, this port has the following changes:
+This library is a manual port of the [Penman Python library](https://github.com/goodmami/penman), with similar method names and import structure. All functionality available in the original library should also be available in this library, with similar usage and semantics. The Python library should still be considered the main project for new features.
 
-- all snake-case function names from the Python library are renamed using camel-case to fit Javascript naming conventions. For example, the function `get_pushed_variable` from Python is renamed to `getPushedVariable` in Javascript.
-- Python tuples are replaced with Javascript arrays
-- Python dictionaries are replaced with Javascript `Map`
-- functions only support positional arguments, since Javascript doesn't support keyword arguments like Python
-- All imports use `penman-js` as the base instead of `penman`. For instance, `from penman.graph import Graph` in Python is replaced with `import { Graph } from "penman-js/graph";` in Javascript.
+The goal of this project is to bring the power of the Penman Python library's AMR parsing and generation to the browser and Node.js. This project does not provide a CLI interface for manipulating AMR, since the Python library already provides the functionality.
 
-Otherwise, refer to the [Penman Python library docs](https://penman.readthedocs.io/en/latest/index.html) for full documentation.
+### AMR
+
+Abstract meaning representation (AMR) captures the meaning of English sentences in a single rooted, directed graph. AMR incorporates [PropBank](https://propbank.github.io/) semantic roles, and can represent a number of linguistic phenomema including coreference, negation, quantity, modality, questions, and many more. AMR is typically written in PENMAN notation, giving this library its name.
+
+AMR for the sentence "He drives carelessly" is shown below:
+
+```
+(d / drive-01
+   :ARG0 (h / he)
+   :manner (c / care-04
+              :polarity -))
+```
+
+To learn more about AMR, check out the [AMR project website](http://amr.isi.edu/). To learn more about PENMAN notation and how it's parsed in this library, visit the [Penman Python docs](https://penman.readthedocs.io/en/latest/notation.html).
 
 ## Disclaimer
 
 This project is not officially affiliated with [AMR](http://amr.isi.edu/) or the [Penman Python library](https://github.com/goodmami/penman).
+
+## Acknowledgements
+
+This library is a manual port of the Penman Python library, and as such, all credit for the original code goes to [github.com/goodmami/penman](https://github.com/goodmami/penman).

docs/docs/quick-start.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Quick start
 
 ## Installation
@@ -14,19 +10,43 @@ npm install penman-js
 
 ## Basic usage
 
-The `decode` function make it easy to parse AMR text in Penman notation into a graph. The `encode` function can likewise turn it back into a string.
+The most faithful representation of AMR text in the library is the `Tree` class. The `parse` function turns an AMR text string into a `Tree`, and `format` does the reverse, turning a `Tree` back into a string.
 
 ```js
-import { encode, decode } from 'penman-js';
+import { parse, format } from 'penman-js';
+
+const t = penman.parse('(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))');
+const [variable, branches] = t.node;
+console.log(variable); // ouput: 'w'
+console.log(branches.length); // output: 3
+const [role, target] = branches[2];
+console.log(role); // output: ':ARG1'
+console.log(format(target));
+// (g / go
+//     :ARG0 b)
+```
 
-g = decode('(b / bark-01 :ARG0 (d / dog))');
-g.triples;
-// [('b', ':instance', 'bark-01'), ('b', ':ARG0', 'd'), ('d', ':instance', 'dog')]
-g.edges();
-// [Edge(source='b', role=':ARG0', target='d')]
+Users wanting to interact with graphs might find the `decode` and
+`encode` functions a good place to start.
+
+```js
+import { encode, decode } from 'penman-js';
+const g = penman.decode('(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))');
+console.log(g.top);
+// 'w'
+console.log(g.triples.length);
+// 6
+console.log(g.instances().map((instance) => instance[2]));
+// ['want-01', 'boy', 'go']
 
 // JS doesn't support keyword parameters, so `undefined` must be passed for optional params
-console.log(encode(g, undefined, undefined, 3));
-// (b / bark-01
-//    :ARG0 (d / dog))
+console.log(encode(g, undefined, undefined, 'b'));
+// (b / boy
+//    :ARG0-of (w / want-01
+//                :ARG1 (g / go
+//                         :ARG0 b)))
 ```
+
+The `decode` and `encode` functions work with one PENMAN
+graph. The `load` and `dump` functions work with
+collections of graphs.

docs/docs/trees-graphs-epigraphs.md

@@ -0,0 +1,61 @@
+# Trees and graphs
+
+On the surface, the structures encoded in a PENMAN AMR string are a tree,
+and only by resolving repeated
+node identifiers (variables) as reentrancies does the actual graph
+become accessible. The Penman library thus accommodates the three
+stages of a structure: the linear PENMAN string, the surface
+[Tree](api.tree#class-tree), and the pure [Graph](api.graph#class-graph).
+Going from a string to a tree is called
+**parsing**, and from a tree to a graph is **interpretation**, while
+the whole process (string to graph) is called **decoding**. Going from
+a graph to a tree is called **configuration**, and from a tree to a
+string is **formatting**, while the whole process is called
+**encoding**. These processes are illustrated by the following figure
+(concepts are not shown on the tree and graph for simplicity):
+
+<div class="light-image-bg">
+![The three stages of PENMAN structure](/img/representations.png)
+</div>
+
+Conversion from a PENMAN string to a `Tree`, and
+vice versa, is straightforward and lossless. Conversion to a
+`Graph`, however, is potentially lossy as the
+same graph can be represented by different trees. For example, the
+graph in the figure above could be serialized to any of these PENMAN
+strings.
+
+```
+  (a / alpha                (a / alpha                     (a / alpha
+     :ARG0 (b / beta)          :ARG0 (b / beta                :ARG0 (b / beta
+     :ARG0-of (g / gamma          :ARG1-of (g / gamma))          :ARG1-of (g / gamma
+        :ARG1 b))              :ARG0-of g)                          :ARG0 a)))
+```
+
+Even more serializations are possible if you do not require the first
+occurrence of a variable to define the node (with its node label
+(concept) and outgoing edges), or if you allow other nodes to be the
+top.
+
+The Penman library therefore introduces the concept of the
+**epigraph** (not to be confused with other senses of _epigraph_, such
+as an inscription on a building or a passage at the beginning of a
+book), which is information on top of the graph that instructs the
+[codec](api.codec#class-penmancodec) how the graph should be
+serialized. The epigraph is thus analagous to the idea of the
+[epigenome](https://en.wikipedia.org/wiki/Epigenome): epigenetic
+markers controls how genes are expressed in an individual as the
+epigraphical markers control how graph triples are expressed in a tree
+or string. Separating the graph and the epigraph thus allow the graph
+to be a pure representation of the triples expressed in a PENMAN
+serialization without losing information about the surface form.
+
+There are currently two kinds of epigraphical markers: layout markers
+and surface alignment markers. Surface alignment markers are parsed
+from the string and stored in the tree then propagated to the graph
+upon interpretation. Layout markers are created when the tree is
+interpreted into a graph. When an edge goes to a new node and not a
+constant or variable, a `Push` marker is
+inserted. When a node ends, a `POP` marker is
+inserted. With these markers, and the ordering of triples, the graph
+can be configured to a specific tree structure.

docs/sidebars.ts

@@ -15,12 +15,12 @@ const sidebars: SidebarsConfig = {
   docSidebar: [
     'intro',
     'quick-start',
+    'trees-graphs-epigraphs',
     {
       type: 'html',
       value: 'API Reference',
       className: 'sidebar-section-label',
     },
-    'api.penman',
     'api.codec',
     'api.constant',
     'api.exceptions',

docs/src/css/custom.css

@@ -38,6 +38,7 @@
   padding: var(--ifm-menu-link-padding-vertical) 0;
 }
 
-.class-methods {
-  padding-left: 20px;
+.light-image-bg {
+  border-radius: var(--ifm-code-border-radius);
+  background-color: rgba(255, 255, 255, 0.9);
 }

typedoc-md-theme/resources/partials/member.declaration.hbs

@@ -2,7 +2,7 @@
 
 {{> comment}}
 
-{{#if typeParameters}}
+{{!-- {{#if typeParameters}}
 
 #### Type parameters
 
@@ -12,7 +12,7 @@
 
 {{/with}}
 
-{{/if}}
+{{/if}} --}}
 
 {{#if type.declaration}}
 

typedoc-md-theme/resources/partials/member.signature.hbs

@@ -10,7 +10,7 @@
 
 {{/with}}
 
-{{#if typeParameters}}
+{{!-- {{#if typeParameters}}
 
 {{#if showSources}}
 
@@ -28,7 +28,7 @@
 
 {{/with}}
 
-{{/if}}
+{{/if}} --}}
 
 {{#if parameters}}
 

typedoc-md-theme/resources/partials/member.sources.hbs

@@ -10,7 +10,7 @@
 
 {{/if}}
 
-{{#if inheritedFrom}}
+{{!-- {{#if inheritedFrom}}
 
 #### Inherited from
 
@@ -20,9 +20,9 @@
 
 {{/with}}
 
-{{/if}}
+{{/if}} --}}
 
-{{#if overwrites}}
+{{!-- {{#if overwrites}}
 
 #### Overrides
 
@@ -32,7 +32,7 @@
 
 {{/with}}
 
-{{/if}}
+{{/if}} --}}
 
 {{! Skip the 'defined in' stuff since we're manually constructing pages }}
 {{!-- {{#if sources}}

typedoc-md-theme/resources/templates/reflection.hbs

@@ -12,7 +12,7 @@
 
 {{/with}}
 
-{{#if model.typeParameters}}
+{{!-- {{#if model.typeParameters}}
 
 ## Type parameters
 
@@ -22,7 +22,7 @@
 
 {{/with}}
 
-{{/if}}
+{{/if}} --}}
 
 {{#ifShowTypeHierarchy}}