summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-04-18 20:28:29 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-04-18 20:28:29 -0400
commit638b1c4cbaa56d5534d1d2c9601b1903e6400ebe (patch)
tree375a1ce35c9f3d6b1ca507b523fea23a14c2e5ca
parentformat spec .md (diff)
explore spec
-rw-r--r--example-autonomous-contract.sda374
-rw-r--r--format-specification.md219
2 files changed, 420 insertions, 173 deletions
diff --git a/example-autonomous-contract.sda b/example-autonomous-contract.sda
new file mode 100644
index 0000000..e306a78
--- /dev/null
+++ b/example-autonomous-contract.sda
@@ -0,0 +1,374 @@
+% SiSU Document Abstraction v0.1
+% Source: the_autonomous_contract.ralph_amissah.sst
+% Note: hand-crafted example showing what the serialized abstraction
+% would look like. The text shown approximates the internal Unicode
+% markers that spineAbstraction would produce.
+
+@meta {
+ title.main: The Autonomous Contract
+ title.subtitle: Reflecting the borderless electronic-commercial environment in contracting
+ title.full: The Autonomous Contract: Reflecting the borderless electronic-commercial environment in contracting
+ creator.author: Amissah, Ralph
+ creator.author_surname: Amissah
+ creator.author_surname_fn: Amissah, Ralph
+ date.published: 1997-10-07
+ rights.copyright: 1997 Ralph Amissah
+ classify.topic_register: SiSU markup sample:article:law;law:international:commercial arbitration|uniform law|harmonization
+ classify.subject: international contracts, international commercial arbitration, private international law
+ language.document: en
+ notes.summary: International commercial law writing on the implications of harmonization of law, globalization and international contracting.
+}
+
+@make {
+ doc_type: article
+ auto_num_top_at_level: 1
+ auto_num_depth: 2
+}
+
+@doc_has {
+ inline_links: 5
+ inline_notes_reg: 47
+}
+
+@toc {
+
+[0] toc
+.part: frontmatter
+.section: toc
+| The Autonomous Contract
+
+[0] toc
+.part: frontmatter
+.section: toc
+| Reflecting the borderless electronic-commercial environment in contracting
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 1. Introduction
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2. In search of autonomy
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.1 The diminishing role of States
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.2 Solutions available within national law
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.2.1 Uniform law and its limitations
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.2.2 Uniform rules and principles
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.2.3 Situation specific standard contracts
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.3 A transnational regulatory order for contracts
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.3.1 International commercial arbitration (ICA)
+
+[0] toc
+.part: frontmatter
+.section: toc
+| 2.3.2 Lex Mercatoria - and its essential link to arbitration
+
+}
+
+@body {
+
+[0] heading :A
+.part: frontmatter
+.segment: title
+| The Autonomous Contract
+
+[0] heading :B
+.part: frontmatter
+| Reflecting the borderless electronic-commercial environment in contracting
+
+[1] heading :1 intro
+.part: body
+.parent: 0
+.last_descendant: 6
+.ancestors: 0 0 0 0 1 0 0 0
+.segment: intro
+| Introduction
+
+[2] para
+.part: body
+.parent: 1
+.indent: 1 0
+.has: notes_reg
+| \u201cGlobalization is unstoppable. Even though it may be only in its
+| early stages, it is already intrinsic to the world economy. We have to
+| live with it, recognize its advantages and learn to manage it.
+
+[3] para
+.part: body
+.parent: 1
+.indent: 1 0
+.has: notes_reg
+| That imperative applies to governments, who would be unwise to attempt
+| to stem the tide for reasons of political expediency. It also goes for
+| companies of all sizes, who must now compete on global markets and learn
+| to adjust their strategies accordingly, seizing the opportunities that
+| globalization offers.\u201d【1 Maria Livanos Cattaui, ⑆/The global
+| economy - an opportunity to be seized⑆/ in ⑆/Business World⑆/ the
+| Electronic magazine of the International Chamber of Commerce (Paris,
+| July 1997) at ┤http://www.iccwbo.org/html/globalec.htm├】
+
+[4] para
+.part: body
+.parent: 1
+.has: links notes_reg
+| At a national level, jurists as lawmakers over time magically create
+| their own reality, that is, the world in which they work, and are
+| certified as oracles.【2 Tangential support for the simile from Hans
+| Petter Graver, ⑆/\u201cDen juristskapte virkeligheten og
+| juristrollen\u201d⑆/ in Jussens Venner (1986) p. 314-324.】 They are
+| proud of their traditions in which they are specialists and about which
+| they tend to be protective.
+
+[5] para
+.part: body
+.parent: 1
+.has: notes_reg
+| ⑆_The autonomous contract⑆_ is a concept based on three ideas, that
+| provide lenses or perspectives with which to view the needs of the
+| international business community as they affect and are affected by a
+| polymorphous set of interrelated issues and areas of law: ⑆*(i)⑆*
+| ⑆/⑆_The \u201cautonomous contract\u201d as an expression of the will
+| that \u201cgoverns\u201d international commerce⑆_⑆/.
+
+[6] para
+.part: body
+.parent: 1
+| The practicability and utility of an \u201cautonomous contract\u201d
+| (e.g. one founded in a-national law) is dependent on its ability to
+| serve the international business community as a suitable risk management
+| tool and to result in improved transaction costs.
+
+[7] heading :1
+.part: body
+.parent: 0
+.last_descendant: 20
+.ancestors: 0 0 0 0 7 0 0 0
+| In search of autonomy
+
+[8] para
+.part: body
+.parent: 7
+| The business community engaged in international commerce has had to find
+| ways to cope with the high degree of legal uncertainty brought about by
+| the crossing of numerous legal systems whose rules are expressed in a
+| multitude of languages.
+
+[9] para
+.part: body
+.parent: 7
+.has: notes_reg
+| ⑆*(1.a)⑆* Use of standard contracts. ⑆*(1.b)⑆* Reference to uniform
+| principles and rules. ⑆*(2.a)⑆* Choice of law of an acceptable
+| state.【5 Criteria for selection might include: familiarity; application
+| of uniform law; neutrality; reputation; language; and convenience.】
+
+[10] para
+.part: body
+.parent: 7
+| The contract is a formal tool used by the business community to
+| structure their relations, for which business practice and economics
+| suggest the importance of a predictable and efficient underlying legal
+| framework.
+
+[11] heading :2
+.part: body
+.parent: 7
+.last_descendant: 14
+.ancestors: 0 0 0 0 7 11 0 0
+| The diminishing role of States
+
+[12] para
+.part: body
+.parent: 11
+.has: notes_reg
+| The paradigmatic concept of law and model of legal order is still that
+| of the sovereign state.【8 E.g. Thomas Wilhelmsson, ⑆/Legal Integration
+| as Disintegration of National Law⑆/ in ⑆/Legal Polycentricity -
+| Consequences of Pluralism in Law⑆/ (1995) pp. 127-147 on p. 128.】
+
+[13] heading :2
+.part: body
+.parent: 7
+.last_descendant: 18
+.ancestors: 0 0 0 0 7 13 0 0
+| Solutions available within national law
+
+[14] heading :3
+.part: body
+.parent: 13
+.last_descendant: 15
+.ancestors: 0 0 0 0 7 13 14 0
+| Uniform law and its limitations
+
+[15] para
+.part: body
+.parent: 14
+.has: notes_reg
+| Selection of the law of a municipal system that applies uniform law is
+| one important step that can be taken within the framework of municipal
+| law, to make the contract more autonomous.【10 Regional efforts with
+| their frequently associated political objectives are outside the scope
+| of this paper.】
+
+[16] heading :3
+.part: body
+.parent: 13
+.last_descendant: 17
+.ancestors: 0 0 0 0 7 13 16 0
+| Uniform rules and principles
+
+[17] para
+.part: body
+.parent: 16
+.has: notes_reg
+| We include in this category, rules and principles governing specific
+| aspects of the contractual relationship,【12 E.g. ⑆/ICC's Incoterms⑆/
+| (1990) and contract clauses on ⑆/Hardship and Force Majeure⑆/.】
+
+[18] heading :3
+.part: body
+.parent: 13
+.last_descendant: 19
+.ancestors: 0 0 0 0 7 13 18 0
+| Situation specific standard contracts
+
+[19] para
+.part: body
+.parent: 18
+| Standard contracts may attempt to be autonomous in themselves, but
+| seldom are, having a limited scope of regulation and depending for their
+| ultimate interpretation and gap filling on the applicable \u201claw\u201d.
+
+[20] heading :2
+.part: body
+.parent: 7
+.last_descendant: 30
+.ancestors: 0 0 0 0 7 20 0 0
+| A transnational regulatory order for contracts
+
+[21] para
+.part: body
+.parent: 20
+| Within the traditional municipal order a limited degree of autonomy is
+| available in contract.
+
+[22] heading :3
+.part: body
+.parent: 20
+.last_descendant: 25
+.ancestors: 0 0 0 0 7 20 22 0
+| International commercial arbitration (ICA)
+
+[23] para
+.part: body
+.parent: 22
+.has: notes_reg
+| It appears accepted that ICA has become the most prevalent means of
+| dispute resolution in international commerce.【15 Alexander Komarov
+| ⑆/Remarks on the Applications of the UNIDROIT Principles⑆/...】
+
+[24] heading :3
+.part: body
+.parent: 20
+.last_descendant: 30
+.ancestors: 0 0 0 0 7 20 24 0
+| Lex Mercatoria - and its essential link to arbitration
+
+[25] para
+.part: body
+.parent: 24
+.indent: 1 0
+.has: notes_reg
+| \u201cThe ⑆/lex mercatoria⑆/ has sufficient intellectual credentials
+| to merit serious study, and yet is not so generally accepted as to
+| escape the sceptical eye.\u201d【20 The Rt. Hon. Lord Justice Mustill,
+| ⑆/The New Lex Mercatoria: The First Twenty-five Years⑆/...】
+
+}
+
+@endnotes {
+
+[0] endnote
+.parent: 3
+| 【1 Maria Livanos Cattaui, ⑆/The global economy - an opportunity to be
+| seized⑆/ in ⑆/Business World⑆/ the Electronic magazine of the
+| International Chamber of Commerce (Paris, July 1997) at
+| ┤http://www.iccwbo.org/html/globalec.htm├】
+
+[0] endnote
+.parent: 4
+| 【2 Tangential support for the simile from Hans Petter Graver,
+| ⑆/\u201cDen juristskapte virkeligheten og juristrollen\u201d⑆/ in
+| Jussens Venner (1986) p. 314-324.】
+
+[0] endnote
+.parent: 4
+| 【3 Rene David suggests the primary constraints on development are
+| \u201cconservatism, routine, prejudice and inertia\u201d...】
+
+[0] endnote
+.parent: 9
+| 【5 Criteria for selection might include: familiarity; application of
+| uniform law; neutrality; reputation; language; and convenience.】
+
+[0] endnote
+.parent: 12
+| 【8 E.g. Thomas Wilhelmsson, ⑆/Legal Integration as Disintegration of
+| National Law⑆/ in ⑆/Legal Polycentricity - Consequences of Pluralism in
+| Law⑆/ (1995) pp. 127-147 on p. 128.】
+
+[0] endnote
+.parent: 15
+| 【10 Regional efforts with their frequently associated political
+| objectives are outside the scope of this paper.】
+
+[0] endnote
+.parent: 17
+| 【12 E.g. ⑆/ICC's Incoterms⑆/ (1990) and contract clauses on
+| ⑆/Hardship and Force Majeure⑆/.】
+
+[0] endnote
+.parent: 23
+| 【15 Alexander Komarov ⑆/Remarks on the Applications of the UNIDROIT
+| Principles of International Commercial Contracts in International
+| Commercial Arbitration⑆/ (1995) in ⑆/UNIDROIT Principles: A New Lex
+| Mercatoria?⑆/ pp. 157-166 on p. 157.】
+
+[0] endnote
+.parent: 25
+| 【20 The Rt. Hon. Lord Justice Mustill, ⑆/The New Lex Mercatoria: The
+| First Twenty-five Years⑆/ in Maarten Bos and Ian Brownlie, Liber
+| Amicorum for the Rt. Hon. Lord Wilberforce, Clarendon Press (Oxford,
+| 1987) pp.149-183.】
+
+}
+
diff --git a/format-specification.md b/format-specification.md
index 087b33d..64e445b 100644
--- a/format-specification.md
+++ b/format-specification.md
@@ -150,7 +150,7 @@ Each object starts with `[OCN] type` where:
```
[1] heading :A
-| 【title text】
+| title text
[5] heading :1 segment_name
| Chapter 1 - Introduction
@@ -293,168 +293,7 @@ with empty strings between consecutive `|` markers.
.links: https://example.org https://other.org
```
-### Complete Example
-
-```
-@meta {
- title.main: The Autonomous Contract
- title.subtitle: Reflecting the borderless electronic-commercial environment in contracting
- creator.author: Amissah, Ralph
- date.published: 1997-10-07
- rights.copyright: 1997 Ralph Amissah
- classify.subject: international contracts, commercial arbitration
- language.document: en
-}
-
-@make {
- doc_type: article
- auto_num_top_at_level: 1
-}
-
-@doc_has {
- inline_links: 5
- inline_notes_reg: 47
-}
-
-@body {
-
-[0] heading :A
-.part: frontmatter
-.segment: title
-| The Autonomous Contract
-
-[0] heading :B
-.part: frontmatter
-| Reflecting the borderless electronic-commercial environment in contracting
-
-[1] heading :1 intro
-.part: body
-.parent: 0
-.last_descendant: 4
-.ancestors: 0 0 0 0 1 0 0 0
-.segment: intro
-| Introduction
-
-[2] para
-.part: body
-.parent: 1
-.indent: 1 0
-.has: notes_reg
-| \u201cGlobalization is unstoppable. Even though it may be only
-| in its early stages, it is already intrinsic to the world
-| economy. We have to live with it, recognize its advantages
-| and learn to manage it.
-
-[3] para
-.part: body
-.parent: 1
-.indent: 1 0
-.has: notes_reg
-| That imperative applies to governments...【1 Maria Livanos
-| Cattaui, ⑆/The global economy⑆/...】
-
-[4] para
-.part: body
-.parent: 1
-.has: links notes_reg
-| At a national level, jurists as lawmakers over time magically
-| create their own reality...【2 Tangential support for the
-| simile...】 ...the business community.【3 Rene David suggests
-| the primary constraints...】
-
-[5] heading :1
-.part: body
-.parent: 0
-.last_descendant: 20
-.ancestors: 0 0 0 0 5 0 0 0
-.segment: in_search_of_autonomy
-| In search of autonomy
-
-[6] para
-.part: body
-.parent: 5
-| The business community engaged in international commerce...
-
-[7] heading :2
-.part: body
-.parent: 5
-.last_descendant: 12
-.ancestors: 0 0 0 0 5 7 0 0
-| The diminishing role of States
-
-[8] para
-.part: body
-.parent: 7
-.has: notes_reg
-| The paradigmatic concept of law and model of legal order is
-| still that of the sovereign state.【8 E.g. Thomas
-| Wilhelmsson...】
-
-}
-
-@endnotes {
-
-[0] endnote
-.parent: 2
-| 【1 Maria Livanos Cattaui, ⑆/The global economy - an
-| opportunity to be seized⑆/ in ⑆/Business World⑆/ the
-| Electronic magazine of the International Chamber of Commerce
-| (Paris, July 1997)】
-
-[0] endnote
-.parent: 3
-| 【2 Tangential support for the simile from Hans Petter
-| Graver...】
-
-}
-
-@bookindex {
-
-[0] bookindex
-| international commercial arbitration: 5-20
-
-[0] bookindex
-| lex mercatoria: 12-19
-
-}
-
-```
-
-## Design Decisions
-
-### Why `|` for text lines?
-
-The pipe prefix makes text content unambiguous at the character level.
-Alternative considered: indentation-based (4 spaces). Rejected because
-the abstraction text can contain leading spaces (preserved whitespace in
-blocks) which would be ambiguous.
-
-The `|` character does not conflict with the internal markup Unicode
-characters. While `|` appears in table cell separators in SiSU source
-markup, by the abstraction stage these have been converted to `┊` (tc_s).
-
-### Why properties before text?
-
-Properties (`.name: value`) appear between the object declaration and the
-text content. This means scanning an object goes: identity -> metadata ->
-content. For downstream processing, the metadata is often needed before
-the text (e.g., to decide how to render it), so this ordering matches the
-access pattern.
-
-### Why one line per property?
-
-Diff-friendliness. When a property changes, only that line shows in a diff.
-When an object is added or removed, the diff is a contiguous block.
-
-### Why preserve internal Unicode markers?
-
-The abstraction's `text` field has already transformed source markup
-(`/{italic}/`) into internal markers (`⑆/italic⑆`). This is the canonical
-form at the abstraction stage. Reverting to source markup would lose
-information about processing decisions (e.g., auto-bolding, substitutions).
-The format represents the abstraction faithfully, not the source.
-
-### What can be omitted?
+### Property Defaults (omission rules)
Properties with default values are omitted to reduce verbosity:
@@ -473,18 +312,17 @@ Properties with default values are omitted to reduce verbosity:
| .code_syntax | "" | empty |
| .code_linenumbers | false | false |
-### What about `ptr` (DocObj_Pointer_)?
+### What is NOT serialized
-The `ptr` struct contains runtime array indices (`doc_object`,
-`html_segnames`, `heading`) that are specific to the in-memory layout.
-These are NOT serialized - they would be recomputed when loading.
+- `ptr` (DocObj_Pointer_) - runtime array indices, recomputed on load
+- Computed properties (object_number(), marked_up_level(), etc.)
+- `heading_lev_collapsed` - derivable from `heading_lev_markup`
-### What about `tags` (DocObj_Tags_)?
+### What is optional
-Tags contain HTML/EPUB-specific identifiers computed during abstraction.
-These ARE serialized because they capture segment structure decisions used
-by multiple output generators. However, they could be recomputed from the
-heading hierarchy if needed, so they're optional for a minimal format.
+- `tags` (DocObj_Tags_) - HTML/EPUB-specific segment identifiers. These
+ capture structure decisions used by multiple output generators. Serialized
+ for completeness but could be recomputed from the heading hierarchy.
## PEG Grammar (Pegged syntax sketch)
@@ -505,7 +343,8 @@ SiSUAbstraction:
ObjDecl <- '[' ~Number ']' sp ~ObjType ObjExtra?
ObjType <- 'heading' / 'para' / 'toc' / 'table' / 'code'
/ 'quote' / 'group' / 'block' / 'verse'
- / 'endnote' / 'glossary' / 'bibliography' / 'bookindex' / 'blurb'
+ / 'endnote' / 'glossary' / 'bibliography' / 'bookindex'
+ / 'blurb'
ObjExtra <- sp ~(!nl .)+
Property <- '.' ~PropName ':' sp ~PropValue nl
@@ -545,3 +384,37 @@ source.sst --> spineAbstraction() --> in-memory objects
The `.sda` file captures the state AFTER parsing and abstraction but BEFORE
output generation. It is independent of any specific output format.
+
+## Design Decisions
+
+### Why `|` for text lines?
+
+The pipe prefix makes text content unambiguous at the character level.
+Alternative considered: indentation-based (4 spaces). Rejected because
+the abstraction text can contain leading spaces (preserved whitespace in
+blocks) which would be ambiguous.
+
+The `|` character does not conflict with the internal markup Unicode
+characters. While `|` appears in table cell separators in SiSU source
+markup, by the abstraction stage these have been converted to `┊` (tc_s).
+
+### Why properties before text?
+
+Properties (`.name: value`) appear between the object declaration and the
+text content. This means scanning an object goes: identity -> metadata ->
+content. For downstream processing, the metadata is often needed before
+the text (e.g., to decide how to render it), so this ordering matches the
+access pattern.
+
+### Why one line per property?
+
+Diff-friendliness. When a property changes, only that line shows in a diff.
+When an object is added or removed, the diff is a contiguous block.
+
+### Why preserve internal Unicode markers?
+
+The abstraction's `text` field has already transformed source markup
+(`/{italic}/`) into internal markers (`⑆/italic⑆`). This is the canonical
+form at the abstraction stage. Reverting to source markup would lose
+information about processing decisions (e.g., auto-bolding, substitutions).
+The format represents the abstraction faithfully, not the source.