Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Some suggestions about documentation formatting

Aperta
#36 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Ambito
documentation, localization

Direzione di ricerca

Start by reviewing the documentation examples cited in the issue, including view.adoc, preprocessor.html, and the Event! datatype example, then inventory the repository's existing formatting conventions. Done means the listed header, emphasis, link, admonition, code-word, type-annotation, and spacing conventions are applied consistently and remain suitable for translation.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Here are some suggestions about the formatting of documentation which came up while I was working on the translation. The goal is to make the documentation look less confusing and more compatible with different translations in terms of formatting.

Document Header

Suggestion: Add an attribute :toc-title: Table of Contents.

Reason: This attribute represents the TOC label. The translator only need to change "Table of Contents" to the translated language without adding a new attribute manually.

Bold and Italic

Suggestion: Always using __text__ and **text** instead of _text_ and *text*.

Reason: Like in Chinese and Japanese, there is no spacing between words, so single _ or * will be treated as normal texts instead of formatting instructions. It is better to avoid translators changing the formatting manually.

Link and Anchor

Suggestion: Always use link:url[text] syntax. Note the link: prefix must be added.

Reason: This can work without spacing around the link. Maybe just I can't figure out how to make << xxx >> work.

Suggestion: Always using link:#a-anchor[text] for links within the document and add an explicit anchor ID [#a-anchor] right above the section title to link.

Reason: The anchor for a section is dependent on the text of that section, which can be messed up after translation. This works across different translations.

Suggestion: Use link:another-document.adoc[text] for links between documents. Note the extension of the link is adoc.

Reason: This makes the link works both on github and gitbook. Gitbook will automatically change .adoc to .html.

Admonition

Suggestion: Always using the syntax described below (NOTE can be other type):

[NOTE, caption=Note]
====
Something to note.
====

Reason: That "Note" of the caption attribute is the label displayed in the left of the admonition block. The translator only need to change into translated language without changing the formatting. The label of inline admonitions (NOTE: ) can't be changed (or maybe I couldn't figure it out).

Word Name

Suggestion: Always surround the word which means Red word with ` (also in section titles, without uppercase).

Reason: Red word (keyword in DSL, or function name) is not that distinguishable from normal English words (in my opinion). If it is used in section titles without surrounded in a code span, it can be hard for translators to decide whether to translate it or not, and also may be confusing for normal readers. I have tried to make it a code span in the section title and it renders good.

Suggestion: Maybe avoid using red-words like normal English words in sentences.

Reason: Like the example below from the description of check in view.adoc, It sounds stupid if I keep left and right as is after translating. Or wrap left and right into a parenthesis and annotate after translating left and right, which also doesn't looks so good.

para: The align field controls if the text is displayed on the left or on the right side.

para: align 字段控制该文本是靠 left 边显示还是靠 right 边显示。

para: align 字段控制该文本是靠左边（left）显示还是靠右边（right）显示。

Type Annotation

Suggestion: Unify the type annotation over all documentation.

Reason: It is good to do so. Currently it can appear in two different kind of contents (see below), function syntax code blocks and some tables. It is not always at the end of a paragraph.

From macro of preprocessor:

#macro <name> func <spec> <body>
#macro <pattern> func <spec> <body>

<name>    : name of the macro function (set-word!).
<pattern> : matching rule for triggering the macro (block!, word!, lit-word!).
<spec>    : specification block for the macro function.
<body>    : body block of the macro function.

From Event! datatype of view:

|`offset`| Offset of mouse cursor relative to the face object when the event occurred (`pair!`). For gestures events, returns the center point coordinates.

Suggestion: Don't use "," to separate multiple types, nor "or" needed.

Reason: Removing these won't cause confusion. The datatype won't lose coloring as the example of #macro above.

Spacing

Suggestion: Always add a separate line between the actual content.

Reason: This can avoid content format corruption in some languages.

Lingua principale
CSS
Stelle
68
Fork
47
Nessuna PR unita negli ultimi 30g

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di red/docs

Tutte le issue di red/docs

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.