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-word
s 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.