The content of sentences is decided in the previous steps (paragraph assembly, sentence conventions, rewriting for readability). This step handles onlyhow to arrangethe fixed sentences.
If you continue to the next sentence without a line break after a long sentence, it is hard to read. In a paragraph where the claim, reason, and specifics are lined up on one line, the reader has to find for themselves where the role changes.
Rules
1. Break lines for each sentence
When a sentence ends with a sentence-ending punctuation mark ("。", "！", "？"), break the line. One sentence per line.
- Do not break at a sentence-ending punctuation mark inside quotation marks (wrote "保管庫です。").
- For parentheses that enclose an entire sentence ((補足です。)), break after the closing parenthesis.
- Do not break inside inline code.
- Do not break lines inside list items, tables, headings, or code blocks. If you break a line inside a list item, in Discord it looks like it has gone outside the item, and in Markdown the continuation line needs indentation. If an item needs two or more sentences, shorten the sentences or make it a paragraph in the body text.
2. Insert blank lines for each role group
The unit separated by a blank line is "a group of sentences with one role." It may be finer-grained than a paragraph. Examples of roles:
- Claim (what it does / what it wants to say)
- Reason / mechanism (why it turns out that way)
- Specifics (where / what / with which numbers)
- Conditions / exceptions (when it differs)
The sentences in a group should be only sentences that continue explaining the same role. When the role changes, insert a blank line.
Even when separated by a blank line, show the relationship between groups (reason, concretization, contrast) within the sentences. A blank line conveys only that "the role changes." Do not delete words that show relationships, such as "そのため" or "具体的には", in place of a blank line.
A group may consist of one sentence. A group of just one sentence may follow immediately after a heading.
Procedure
Paths are relative to the directory containing this SKILL.md.
- Run
python3 scripts/layout.py <file> --fixon the text you have written, and break lines for each sentence. - Read the paragraphs for which the same script reports "the paragraph has N sentences," and insert blank lines according to role. Even for paragraphs without a report, split them if two or more roles are mixed together.
- If, as a result of inserting blank lines, the claim of a group no longer connects with what comes before or after, supplement the connection with sentences (return to paragraph assembly).
Display notes
In places like GitHub where a single line break in Markdown is displayed as a single space, line breaks per sentence are not visually apparent. Therefore, the only thing that creates a visual separation is a blank line (paragraph), so separate blocks of roles with blank lines. In Discord and Qiita, a single line break is displayed as-is, so line breaks per sentence are visible as they are.
Scripts and tests
scripts/layout.py— inspection (violations exit with code 1) and--fix(a machine inserts only line breaks per sentence. It does not insert blank lines).tests/test_layout.py—python3 -m unittest discover -s tests