Skip to content

Commit 4d0b073

Browse files
committed
docs: build the Word editions from a plain template with absolute links
The Word editions of the specifications carried the O-RAN logo, the O-RAN ALLIANCE copyright, a working group on the cover and a Foreword and Modal verbs clause that named O-RAN. They are not O-RAN ALLIANCE documents, so tools/oran_docx now builds an O-RAN-like edition: the layout of an O-RAN Technical Specification, the front matter of libe3. * template.docx has no logo, no working group and no rule across the cover. The copyright page names Northeastern University and the Apache License 2.0, the footers carry only the page number at the right margin, the Foreword says who produced the document and the Modal verbs clause refers to the ETSI Drafting Rules. The unused logo and the KPM figure left over from the cut are gone. * make_template.py writes that front matter as part of making the template from the O-RAN specification. The docx.json field group and DEFAULT_GROUP of build_docx.py are gone, with the E2SM-DAPP override. * build_docx.py writes the document number into the TitlesOfParts property, which still held the placeholder of the O-RAN template. * The Scope of each specification says that the document is generated from the codebase and protocol definitions of libe3. The Word edition has no files to link to, so build_docx.py turns each link into a reference a reader can follow: a link to a part of the same specification becomes its clause ("clause 8", "Annex A", "clause 6.2" with an anchor), any other link an absolute GitHub URL, and the sentence "The index is README.md." is left out. The Markdown edition keeps its relative links. The references to the other specifications of the series give their document number, title and GitHub folder, the E2GAP reference has one spelling, a plain "see 02" in E2SM-DAPP is a link, and the Spectrum note on hyperlinks no longer names O-RAN. The four Word editions are rebuilt in the container. Assisted-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 42ee5a5 commit 4d0b073

14 files changed

Lines changed: 324 additions & 90 deletions

‎docs/e2sm-dapp/05-semantics-and-constraints.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Table: Identifiers and their ranges
4343
| `dapp-id` | the dApp | `0..4294967295` | `1..65535` | |
4444
| `SubscribedE3RANFunction-ID` | an E3 RAN function a dApp has subscribed to | `0..4294967295` | `1..65535` | |
4545
| `sequence-id` | one detection-to-mitigation procedure | unbounded, optional | `1..4294967295` (`E3-SequenceID`) | **`E3-SequenceID` equals E2SM-DAPP `sequence-id`**: same value, assigned by the dApp, never reassigned. |
46-
| `node-type`, `node-plmn-id`, `node-nb-id`, `node-cu-du-id` | identity of the reporting node | see 02 | | the grammar defines no enumeration and no packing. See 02. |
46+
| `node-type`, `node-plmn-id`, `node-nb-id`, `node-cu-du-id` | identity of the reporting node | see [02](02-ie-mapping.md) | | the grammar defines no enumeration and no packing. See [02](02-ie-mapping.md). |
4747

4848
**A sender should keep the E2SM-DAPP ids inside the E3 ranges.** E2SM-DAPP can carry
4949
`0` and values above `65535`. A RAN that relays a control over E3 cannot deliver them,
-46.2 KB
Binary file not shown.

‎docs/e2sm-dapp/README.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ The present document defines the RAN function definition, the information elemen
2626
the procedures of this service model. It also defines the APER encoding of the
2727
information elements and the handling of unknown and erroneous data.
2828

29+
This document is generated from the codebase and protocol definitions for the libe3
30+
implementation in https://github.com/wineslab/libe3.
31+
2932
## References
3033

3134
### Normative references
@@ -37,7 +40,7 @@ applies. For a non-specific reference, the latest version applies.
3740
The following referenced documents are necessary for the application of the present
3841
document.
3942

40-
1. O-RAN-WG3.TS.E2GAP: "O-RAN E2 General Aspects and Principles".
43+
1. O-RAN.WG3.TS.E2GAP: "O-RAN E2 General Aspects and Principles".
4144
2. O-RAN.WG3.TS.E2AP: "O-RAN E2 Application Protocol (E2AP)".
4245
3. O-RAN.WG3.TS.E2SM: "O-RAN E2 Service Model (E2SM)".
4346
4. ITU-T Recommendation X.680: "Information technology: Abstract Syntax Notation One (ASN.1): Specification of basic notation".
@@ -49,15 +52,15 @@ document.
4952
The following referenced documents are not necessary for the application of the present
5053
document, but they help the reader.
5154

52-
1. The E3 Application Protocol (E3AP) specification, [../e3ap/README.md](../e3ap/README.md).
55+
1. O-RAN.XXX.TS.E3AP-R000-v00.01: "E3 Application Protocol (E3AP)", https://github.com/wineslab/libe3/tree/main/docs/e3ap.
5356
2. The OpenAirInterface implementation of E3AP and of this service model: https://github.com/duranta-project/openairinterface5g/pull/729.
5457

5558
## Terms, symbols and abbreviations
5659

5760
### Terms
5861

59-
For the purposes of the present document, the terms and definitions given in O-RAN
60-
WG3.TS.E2GAP [1], O-RAN.WG3.TS.E2SM [3] and the following apply.
62+
For the purposes of the present document, the terms and definitions given in
63+
O-RAN.WG3.TS.E2GAP [1], O-RAN.WG3.TS.E2SM [3] and the following apply.
6164

6265
* **dApp**: an application that runs next to the E2 node and talks to it over E3.
6366
* **dApp E3 subscription map**: the list of the dApps connected to the E2 node, each with the E3 RAN functions it has subscribed to.

‎docs/e2sm-dapp/docx.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
"number": "O-RAN.XXX.TS.E2SM-DAPP-R000-v00.01",
33
"title": "E2 Service Model dApp (E2SM-DAPP)",
44
"cover": ["E2 Service Model (E2SM)", "dApp (E2SM-DAPP)"],
5-
"group": {"cover": ["O-RAN Work Group 3", "Near-Real-time RAN Intelligent Controller"], "foreword": "WG3"},
65
"parts": [
76
{"clause": "1", "title": "Scope", "file": "README.md", "section": "Scope"},
87
{"clause": "2", "title": "References", "file": "README.md", "section": "References"},
-46.2 KB
Binary file not shown.

‎docs/e3ap/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ how a RAN node produces telemetry or applies a control action. It does not defin
1919
the E2 interface. The E2SM-DAPP specification defines how a RIC reaches a dApp
2020
through the E2 interface. See the [E2SM-DAPP specification](../e2sm-dapp/README.md).
2121

22+
This document is generated from the codebase and protocol definitions for the libe3
23+
implementation in https://github.com/wineslab/libe3.
24+
2225
## References
2326

2427
### Normative references
@@ -43,9 +46,9 @@ References are specific. Only the cited version applies.
4346

4447
[i.1] Protocol Buffers Language Guide (proto3), https://protobuf.dev/programming-guides/proto3/.
4548

46-
[i.2] The E2SM-DAPP specification of this series. See [../e2sm-dapp/README.md](../e2sm-dapp/README.md).
49+
[i.2] O-RAN.XXX.TS.E2SM-DAPP-R000-v00.01: "E2 Service Model dApp (E2SM-DAPP)", https://github.com/wineslab/libe3/tree/main/docs/e2sm-dapp.
4750

48-
[i.3] The E3SM Spectrum and E3SM L1-KPM specifications of this series. See [../e3sm/README.md](../e3sm/README.md).
51+
[i.3] O-RAN.XXX.TS.E3SM-SPEC-R000-v00.01: "E3 Service Model Spectrum (E3SM-SPEC)", https://github.com/wineslab/libe3/tree/main/docs/e3sm/spectrum, and O-RAN.XXX.TS.E3SM-L1-KPM-R000-v00.01: "E3 Service Model (E3SM), L1 KPM (E3SM-L1-KPM)", https://github.com/wineslab/libe3/tree/main/docs/e3sm/l1-kpm.
4952

5053
[i.4] The OpenAirInterface implementation of E3AP, https://github.com/duranta-project/openairinterface5g/pull/729.
5154

-46.2 KB
Binary file not shown.

‎docs/e3sm/l1-kpm/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@ The present document does not define E3AP messages or procedures. They are defin
4444
[1]. It does not define how a RAN node computes the values that it reports. It does not
4545
define the transport between the dApp and the E3 Agent.
4646

47+
This document is generated from the codebase and protocol definitions for the libe3
48+
implementation in https://github.com/wineslab/libe3.
49+
4750
## References
4851

4952
### Normative references
@@ -53,7 +56,7 @@ References are specific. Only the cited version applies.
5356
The following referenced documents are necessary for the application of the present
5457
document.
5558

56-
[1] "[E3 Application Protocol (E3AP)](../../e3ap/README.md)", R000 v00.01.
59+
[1] O-RAN.XXX.TS.E3AP-R000-v00.01: "E3 Application Protocol (E3AP)", https://github.com/wineslab/libe3/tree/main/docs/e3ap.
5760

5861
[2] ITU-T Recommendation X.680 (2002-07): "Information technology: Abstract Syntax Notation One (ASN.1): Specification of basic notation".
5962

-45.8 KB
Binary file not shown.

‎docs/e3sm/spectrum/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ The document does not define the E3 Application Protocol. It does not define the
3333
E2 service model that carries dApp traffic to an xApp. It does not define how a
3434
scheduler enforces a PRB block internally.
3535

36+
This document is generated from the codebase and protocol definitions for the libe3
37+
implementation in https://github.com/wineslab/libe3.
38+
3639
## References
3740

3841
### Normative references
@@ -43,12 +46,12 @@ applies. For non-specific references, the latest version of the referenced docum
4346
applies.
4447

4548
> NOTE: While any hyperlinks included in this clause were valid at the time of
46-
> publication, O-RAN cannot guarantee their long-term validity.
49+
> publication, their long-term validity cannot be guaranteed.
4750
4851
The following referenced documents are necessary for the application of the present
4952
document.
5053

51-
[1] E3AP specification: "E3 Application Protocol (E3AP)", see [the E3AP specification](../../e3ap/README.md).
54+
[1] O-RAN.XXX.TS.E3AP-R000-v00.01: "E3 Application Protocol (E3AP)", https://github.com/wineslab/libe3/tree/main/docs/e3ap.
5255

5356
[2] ITU-T Recommendation X.680 (2002-07): "Information technology: Abstract Syntax Notation One (ASN.1): Specification of basic notation".
5457

0 commit comments

Comments
 (0)