Add a skill that imports the version 5 chapters from SharePoint.

---

name: importing-version-5-content

description: Imports the TTCN-3 version 5 working documents from the ETSI SharePoint folder Version_5_Content into src/ as Markdown. One subagent per Word file accepts all tracked changes on a temporary copy, removes everything the file name does not name (ETSI skeleton, editorial notes, annex placeholders, history), repairs the heading structure, runs t3s import, and formats TTCN-3 examples with t3s format. Use when the user asks to import, convert, sync or refresh the version 5 (v5) content, the SharePoint chapters, or the Version_5_Content .docx files into src/.

---

# Importing Version_5_Content

Files in this skill:

- [brief.md](brief.md): the subagent brief for one Word file. Send it verbatim with the

  placeholders filled in.

- [scripts/docx-tool.py](scripts/docx-tool.py): accepts tracked changes and edits the outline

  of a `.docx` (`outline`, `text`, `delete`, `delete-section`, `restyle`, `shift`, `retext`,

  `split`). Run it with `--help` for the commands.

The `.docx` files are never edited in the SharePoint download. Every subagent works on its

own copy in a temporary directory.

## Workflow

```

Import progress:

- [ ] 1. Locate the Version_5_Content folder

- [ ] 2. Check the tools and build t3s

- [ ] 3. Select the files and prepare the work directories

- [ ] 4. One subagent per file, in parallel

- [ ] 5. Check the results and report

```

**1. Locate the folder.** Use the local path the user gave. Without one, look for a

downloaded `Version_5_Content` folder the user names, or download it with an

`etsi-sharepoint` skill if one is available (SharePoint path

`/teams/TTFT056/Shared Documents/General/4_Working_Documents/Version_5_Content`). Otherwise

ask the user to download the folder from SharePoint and give its path. Do not reimplement

SharePoint access.

**2. Tools.** From the repository root:

```bash

python3 -c 'import lxml' || pip install --user lxml

WORK=$(mktemp -d /tmp/v5-import.XXXXXX)

(cd tools && go build -o "$WORK/t3s" ./cmd/t3s)

```

LibreOffice and WordCraft are not used to accept the changes: saving through LibreOffice

recomputes cross-reference fields ("Error: Reference source not found"), joins paragraphs

and changes notes and table captions. `docx-tool.py accept` edits the OOXML directly and

leaves everything else as Word wrote it.

**3. Select the files.** Take every `*.docx` directly inside Version_5_Content. Skip:

- subfolders, such as "Backup versions of chapters";

- files whose name contains "backup" or "topics to discuss" (case-insensitive), such as

  `0000 Topics to discuss.docx`;

- Word lock files (`~$*.docx`) and non-Word files (`.xlsx`).

List the selected and skipped files to the user before starting. For each selected file,

create `$WORK/<n>/` (`n` counts from 1) and copy the file into it **with its original file

name**: t3s numbers the clause from the file name prefix (`06 - Data types.docx` is

clause 6, `C - Predefined functions.docx` is annex C).

**4. Subagents.** Launch one subagent per file, all in parallel (in batches if the tool

limits concurrency). Each gets [brief.md](brief.md) with `{REPO}` (absolute repository

root), `{TOOL}` (absolute path of `scripts/docx-tool.py`), `{T3S}` (`$WORK/t3s`), `{DIR}`

(`$WORK/<n>`) and `{FILE}` (the file name) filled in. The brief is self-contained; do not

add the conversation.

The parent does not read the documents. It only collects the reports.

`16-declaring-behaviour.docx` is the one exception to "keep what the file name names": its

subagent keeps the two sections Parameterization and "Functions, altsteps and testcases",

and imports them as `src/16-parameterization.md` and

`src/17-functions-altsteps-and-testcases.md`. The brief describes how.

**5. Check and report.**

- Every subagent reported `status: done`. Rerun a failed file once with a fresh copy; then

  report it as failed.

- No two subagents wrote the same Markdown file name. If they did, the later import

  overwrote the earlier one: report both sources and rerun them one after the other with

  the user's decision.

- No `src/1000*.md` exists (t3s writes 1000 for a second top-level heading without a number,

  which means leftover content).

- `git status --short src` and `git diff --stat src`: list new, changed and unchanged files.

- Each written file reads back: `"$WORK/t3s" extract examples -o "$WORK/examples/<name>"

  src/<name>.md`, one file at a time (several drafts share clause numbers, so a run over all

  of `src` reports collisions). Report errors per file. Do not fix the Markdown by hand.

- Every written file was formatted: the subagent ran `"$WORK/t3s" format src/<name>.md`.

  Blocks that do not parse stay as they are and are listed in the report; other blocks are

  still formatted. Do not re-run format over all of `src` (clause numbers collide).

Report to the user, one line per source file: the Markdown file(s) written, the sections

removed, the structural repairs, and the warnings the subagent raised (unresolved

references, empty headings, content it was unsure about). Do not commit unless the user asks.

Remove `$WORK` after the report, unless the user wants to inspect the cleaned copies.

## t3s import rules that drive the cleanup

- Everything before the first `heading 1` is skipped, and that heading is numbered from the

  file name. So the first `heading 1` must be the chapter itself.

- Every later `heading 1` starts another top-level file. A clean chapter has exactly one

  `heading 1`; every other heading is level 2 or deeper.

- Typed numbers in headings (`6.1.2`) are dropped and the clauses are counted, so wrong or

  placeholder numbers (`X.1`, `26.`) need no repair.

- Annex files (A–E) start in Word with an annex title in `heading 8` ("Annex C (normative):

  Predefined TTCN-3 functions") and their clauses in `heading 1`. The cleanup turns the annex

  title into a `heading 1` with the title only and moves all annex clauses one level down.

- Tracked deletions of a paragraph mark join two paragraphs when the changes are accepted,

  exactly as in Word. A heading that absorbed a code line or a sentence is flagged

  `MERGED?` by `docx-tool.py outline` and repaired with `split` and `restyle`.

# Subagent brief: import one Version_5_Content file

Fill in the placeholders and send the text below as the subagent prompt.

---

Import one TTCN-3 version 5 working document into Markdown.

- Repository: `{REPO}`

- Tool: `python3 {TOOL}` (below: `docx-tool`). `docx-tool --help` lists the commands.

- t3s: `{T3S}`

- Work directory: `{DIR}`; the copy to work on is `{DIR}/{FILE}`. Never touch any other

  `.docx` file, and never rename this copy unless step 5 says so: t3s takes the clause

  number from the file name prefix.

Do not change wording, fix typos, or renumber clauses. Only accept changes, remove content,

and repair structure. Every edit is in place; run `docx-tool outline` again after each edit,

because block indexes shift. All indexes in one command refer to the outline before it.

`N-end` runs to the last block.

1. **Accept all changes.** `docx-tool accept "{DIR}/{FILE}"`. It must report

   `0 revisions left`. It also removes review comments.

2. **Read the outline.** `docx-tool outline "{DIR}/{FILE}"` lists headings (`#` per level,

   then the style) and suspicious paragraphs (`?`). `outline --all` lists every block, and

   `text FILE N-M` prints whole blocks. Decide which clause the file name names: for

   `06 - Data types.docx` it is "6 Types and values", for `C - Predefined functions.docx`

   it is annex C, for `03 - Definition of terms, symbols and abbreviations.docx` it is

   clause 3.

3. **Remove everything else.** Use `delete FILE N-M ...` for block ranges and

   `delete-section FILE N ...` for a heading with all its content. Remove:

   - the ETSI skeleton before the chapter: cover and title page, table of contents,

     "Intellectual Property Rights", "Foreword", "Modal verbs terminology", "Executive

     summary", "Introduction", "1 Scope", "2 References", and "3 Definition of terms,

     symbols and abbreviations" (except in the clause 3 file);

   - template placeholders: "4 User defined clause(s) from here onwards" and its

     subclause, "Annex A (normative or informative): Title of annex", "<Text>." paragraphs;

   - "Bibliography", "Change history", and "History" with their tables;

   - editorial notes, notes to editors, TODO and TBD remarks, open questions and

     discussion text addressed to the drafting team (not `NOTE:` paragraphs in the `NO`

     style, which are part of the standard);

   - other clauses that are not part of the named clause.

   An empty heading directly followed by another heading of the same or a higher level is

   deleted. An empty heading with content below it stays; report it. Empty `NO` and `EX`

   paragraphs (flagged `(empty)`) are deleted; they would become stray `NOTE:` labels.

4. **Repair the structure for t3s.**

   - The first heading must be a `heading 1` holding the chapter title. There must be no

     other `heading 1`, and no other heading above level 2 after it.

   - Annex file: the annex title is a `heading 8` such as "Annex C (normative): /

     Predefined TTCN-3 functions". First `shift FILE N-M 1` over all annex clauses

     (they are `heading 1` and deeper), then `restyle FILE N "heading 1"` and

     `retext FILE N "Predefined TTCN-3 functions"` on the annex title (title only, without

     "Annex C (normative):").

   - A heading flagged `MERGED?` absorbed a neighbouring paragraph when its deleted

     paragraph mark was accepted. Print it with `text`, `split FILE N "TEXT"` before the

     real heading text (or after the heading, before the absorbed text), and restyle the

     absorbed part to the style of the paragraphs around it (`PL` for code, `Normal` for

     prose, see `outline --all`). In TEXT, `\t` stands for a tab, as `text` shows them.

     Repair only headings this way; joined body paragraphs and joined code lines are left

     as they are and reported.

5. **Only for `16-declaring-behaviour.docx`.** Keep the two sections Parameterization and

   "16 Functions, altsteps and testcases"; remove everything else as above. Make two

   copies of the accepted file in `{DIR}`: `16-parameterization.docx` and

   `17-functions-altsteps-and-testcases.docx`, and remove `{DIR}/{FILE}`.

   - In `16-parameterization.docx` keep only Parameterization: make its title a

     `heading 1` ("Parameterization") and shift its subclauses so the first level below

     it is `heading 2`.

   - In `17-functions-altsteps-and-testcases.docx` keep only "Functions, altsteps and

     testcases", starting at its `heading 1`.

   Apply steps 6, 7 and 8 to both files.

6. **Check.** `rm -rf "{DIR}/md" && {T3S} import -o "{DIR}/md" "{DIR}/<file>.docx"`.

   It must write exactly one Markdown file, and none named `1000*.md`. Read the file once:

   - the first line is `# <chapter title>`;

   - no skeleton, placeholder, history or editorial text is left;

   - code is in fences, not in headings.

   Fix the `.docx` and import again until the result is clean. Count the broken

   cross-references with `grep -o 'Error: Reference source not found' "{DIR}"/md/*.md | wc -l`;

   they come from the source and are only reported.

7. **Import into the repository.** Run from `{REPO}`:

   `{T3S} import -f -o src "{DIR}/<file>.docx"`.

8. **Format TTCN-3 examples.** From `{REPO}`, run `{T3S} format src/<name>.md` on each

   Markdown file written in step 7. It rewrites TTCN-3 fences in place. A block that does

   not parse is left unchanged and reported at its line; the other blocks are still

   formatted. Exit 1 with parse errors is expected for joined code lines: keep the file

   and list those errors. Do not edit the Markdown by hand to make a block parse.

Report back in this form, and nothing else:

```

source: {FILE}

status: done | failed (<reason>)

written: src/<name>.md [, src/<name>.md]

removed: <headings or descriptions of removed parts, comma-separated>

repaired: <structural repairs, or none>

formatted: ok | N TTCN-3 blocks left unparsed (<file:line, …>)

warnings: <unresolved references count, empty headings kept, uncertain removals, or none>

```

# TTCN-3 overview

## Type Expression

The type expression `template(omit)` may be replaced by the shorthand notation

`omit`.

**Examples**

```ttcn3 example="template(omit) shorthand in declarations"

var omit integer t1; // expect: typeof(t1) == "template(omit) integer"

```

```ttcn3 example="template(omit) shorthand in return-type"

external function f() return omit integer;

```

```ttcn3 example="template(omit) shorthand in formal parameter lists"

function f(in omit integer p) { /* … */ }

```