diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-04-18 20:28:29 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-04-18 20:28:29 -0400 |
| commit | 638b1c4cbaa56d5534d1d2c9601b1903e6400ebe (patch) | |
| tree | 375a1ce35c9f3d6b1ca507b523fea23a14c2e5ca | |
| parent | format spec .md (diff) | |
explore spec
| -rw-r--r-- | example-autonomous-contract.sda | 374 | ||||
| -rw-r--r-- | format-specification.md | 219 |
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. |
