Repository navigation
docs: build the Word editions from a plain template with absolute links - #142
Merged
Merged
Conversation
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>
Contributor
CI report —
|
| Workflow | Result | Time | Run |
|---|---|---|---|
| Commit policy | ✅ success (steps skipped — no code changes) | 0m16s | #224 |
| Docs | ✅ success | 0m28s | #27 |
| Build libe3py wheels | ⏭️ not started (no changed file matches its paths filter) |
— | — |
| E2E dApp Integration | ⏭️ not started (no changed file matches its paths filter) |
— | — |
| E2E Topologies (multi-dApp / multi-RAN) | ⏭️ not started (no changed file matches its paths filter) |
— | — |
| Full-loop Latency Benchmark | ⏭️ not started (no changed file matches its paths filter) |
— | — |
| latrec portability | ⏭️ not started (no changed file matches its paths filter) |
— | — |
| MPMC Queue Benchmark | ⏭️ not started (no changed file matches its paths filter) |
— | — |
| Unit Tests | ⏭️ not started (no changed file matches its paths filter) |
— | — |
Docs
Doxygen warnings
0 warning(s) in the files this pull request changes, which fail the check; 403 more elsewhere, which do not. The full list is in the job log and the doxygen-warnings artifact of the Docs workflow.
Gaps in files this pull request does not change, by file:
| Warnings | File |
|---|---|
| 53 | include/libe3/types.hpp |
| 37 | include/libe3/sm_interface.hpp |
| 35 | include/libe3/e3_connector.hpp |
| 34 | include/libe3/e3_agent.hpp |
| 32 | include/libe3/e3_interface.hpp |
| 29 | include/libe3/c_api.h |
| 19 | src/c_api.cpp |
| 17 | include/libe3/logger.hpp |
| 17 | swig/libe3_swig.hpp |
| 17 | swig/e3_dapp_session.hpp |
Ready to merge (fast-forward only)
A maintainer can land the reviewed commits with:
git fetch origin
git checkout main && git merge --ff-only 4d0b073170f254f5f1b5fc59e5ea87321ede0d73 && git push origin mainHead: 4d0b073170f254f5f1b5fc59e5ea87321ede0d73 (branch docs/oran-docx-plain-template). If --ff-only fails as non-fast-forward, the branch must be rebased on the latest main.
One comment per PR, rewritten in place once every workflow for
4d0b073finished.
2 of 9 tasks
Thecave3
approved these changes
Nov 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Plain template. The Word editions are O-RAN-like, not O-RAN ALLIANCE documents: they keep the layout of an O-RAN Technical Specification but have no O-RAN 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, the Foreword says who produced the document, and the Modal verbs clause refers to the ETSI Drafting Rules.
make_template.pywrites this front matter when it makestemplate.docx. Thegroupfield ofdocx.jsonand the E2SM-DAPP override are gone.Acknowledge libe3. The Scope of each specification (E3AP, E2SM-DAPP, E3SM Spectrum, E3SM L1-KPM) says: "This document is generated from the codebase and protocol definitions for the libe3 implementation in https://github.com/wineslab/libe3."
Fix links. A Word edition can't follow relative Markdown links, so
build_docx.pyturns each one into a reference a reader can follow:[04-encoding.md](04-encoding.md)[06](06-discrepancies.md)[the style table](#e2-service-formats)[the latency recorder](../utilities/latrec.md)The Markdown edition keeps its relative links. References to the other specifications of the series now give the document number, the title and the GitHub folder. Some smaller fixes are included: the E2GAP reference has one spelling, a plain "see 02" in E2SM-DAPP is now a link, the Spectrum note on hyperlinks no longer names O-RAN, and the
TitlesOfPartsdocument property gets the document number instead of the O-RAN template placeholder.All four Word editions are rebuilt in the
tools/oran_docxcontainer.template.docxwas checked part by part against the output of the restructuredmake_template.py. The original O-RAN source (O-RAN.WG3.TS.E2SM-KPM-R005-v08.00.docx) is not in the repository, so the check ran on the committed template with the cut skipped.Type of change
Linked issue
No issue is open for this change. It touches only the documentation and its Word tooling.
Twin-repo coordination
libe3 is paired with
dappsanddApp-openairinterface5g. We do not accept patches that break or reduce compatibility with the twin repositories.docs/interop.md.Paired PR(s): none needed (documentation only).
🤖 Generated with Claude Code