Tkabber Wiki:Help (en)
Материал из Tkabber Wiki
This page is written for those who would like to take part in the Tkabber Wiki project as an author or a translator. The goal of the following text is to define a common style of Tkabber Wiki articles so that they would look more or less identical, were not too variegated with bold and italic styles and were clear for understanding.
If you have got some suggestions about the wiki's style, please contact Участник:bigote, or Участник:kostix, or Участник:lknight. All of them speak English.
There is a conference xmpp:tkabber-wiki@confernce.jabber.ru created for discussing our wiki work progress and its problems. It is invite-only, so if you would like to enter it, please contact us first.
Well, let's begin.
Содержание |
If you have no experience with wikis
- There is a complete and quite decent manual about WikiPedia editing. That page contains links to more specific themes like "Images", "How to start a new page", etc. It is an ideal place for beginners.
- However, it is more convenient to take a look at the correspondent page of MediaWiki to build galleries, which shows you a correct piece of code (it is strange but at wikipedia.org gallery building is explained in few words, and there is no example of working code, so one has to think and try long enough to make something decent ;))
- You can also read interface setting documentation and MediaWiki User's Manual.
About Tkabber Wiki style
First, please remember that the Wiki's structure may change (by you, too, of course) but it should be done with caution, discussing such changes previously with the project admiministrators (see links above). If an article you want to "move" along the wiki has other language versions, they also should be moved. So we would like to ask you notify us about desired changes beforehand.
For new article authors
Before you start writing a new article, look if there is no article that explains that topic more or less completely. If there is such an article, maybe you should just add some material. If there is no article about your desired topic, first decide at which section to place a link to your article and... place it :) Then you can begin writing. Don't think you are wasting time reading these rules of the wiki style. It will help you later, while writing and editing your texts so that they look nice and understandable. It could be helpful to read a source code of some existing wiki article that contains elements you would like to apply to yours. Of course, we are far away from cutting your way of expression, at last, the contents is more important that its form. The article's look is it's author business, just try not to forget about the readers: it's them who will have a head-ache if the author makes his or her text unclear. Do not forget that you can preview the article before saving it. And one more thing: try not to make mistakes ;)
Another important question is about article names. You can read more about it at Wikipedia pages (there are a lot of links to it here already). Our wiki has a nuance about it we would like to explain here. The matter is that other language versions here should be named differently from wikipedia.org since we do not have language subdomains. We have a "suffix system" to arrange language problems here. To create a new article in English a suffix (en) should be added at the end of its name, and it must be separated by a space, like this: "Tkabber Wiki:Help (en)". If we need to create another aticle with the same name but in other language, we would put another suffix at the end instead of (en), for instance, (es). Read more about it at the translators' part.
Now about styles.
Indentation by a space
One of integrated wiki markup styles is indentation by a space, i.e. a line begins with a space. A piece of text marked this way is put in a nice mark with pink background. We use this style for:
- source code:
namespace eval emoteicons {
array set emoteicons {}
variable lasttext ""
variable lastX
variable lastY
}
- settings options when it is the first time we found them in the text:
::jidlink::transport(allowed,dtcp-active)
- path to files when:
- it is quite long,
- it is entered into the text for the first time,
- you want the reader to pay special attention to it.
Try to construct your phrase so that it were not cut by such box or at least looked decent.
Using HTML
Many markup styles are already in the wiki engine, so there is no much need of using HTML tags. What is more, too many tags make article source code more "dirty", make it more difficult translating and editing it. Nevertheless, using HTML tags in some cases is quite defensible. For example, a dash "—" which should be used instead of a hyphen "-" in some sentence places. Other examples: arrows → and ←, angle brackets < and >, the accent symbol ́ that goes after a vocal we would like to accent (cyrillic only!).
If you would like to put a gap in source code, you might want to use a · symbol: "·"
For example:
proc a b {
puts ouch!
· · · · ·
puts text
}
When using links, exclude punctuation marks that touch the last word of a link. For example, In case of doubt do not forget of previewing and of the '''[[Sandbox]].''' → In case of doubt do not forget of previewing and of the Sandbox.
Using <tt> tag
- JID of patch and article authors and of just good people, and also conferences and other resources are marked with <tt> tag: xmpp:loginname@jabberserver.org, xmpp:conferencename@conference.jabberserver.org, rss@jabberserver.org. If there is a punctuation mark going right after a JID or a resource, it should be put after the closing tag </tt>.
- To mark settings options (for instance, ::jidlink::transport(allowed,dtcp-active)), when it is found in the article text for the second or more time.
Using bold
Bold text is used in this wiki for:
- marking paths to the files you are speaking about (for example, ~/.tkabber/avatar.gif) in case it is better not to cut a sentence. Try to construct the phrase so that natural punctuation would not intervene with the path. If it is impossible, exclude punctuation marks from bold marking.
- marking paths to some Tkabber Customize options or its menu items (for example, Customize → File Transfer → Jidlink or Service → Extensions → Spy);
- marking links to other articles of this wiki (for example, "Read more about plugins in this article.");
- drawing attention to some important word;
- note that in case of emphasizing "important words", unlike source code or paths, punctuation marks are also in bold.
- entire questions in Tkabber FAQ are bold, including the "Question" word.
Using italic
Italic is used in our wiki for emphasizing quite long phrases or even paragraphs in a discourse (a sentence or a part of a complex sentence at least), i.e. in cases when bold text draws so much attention that it looks almost ugly. Punctuation marks are included into italic in this case. If you need to accent some word within italized text it is possible to use bold for it. In this case a punctuation mark that touches a bolded word should be also set in bold if it is a common word, and it is excluded from marking if it is a code line or a path: ~/.tkabber/config.tcl. (I understand that it is quite complicated but take a look at the code of this page and you will get it. Or just look at the final dot of the previous sentence — it is not bold :)) Try to avoid styles mixing or placing bold and italic text next to each other.
If you need to put an entire paragraph or several phrases in italic it is better to use <cite> tag.
Using smilies in the text
If you like smilies use it, but, as a friend of mine says, without frenzy ;) So, try to reduce their presence in your texts to the minimum. I has been reflecting for a long time upon final smilies and final punctuation marks, and it seems to me that a smilie could be used instead of final dots ;) It looks strange after a final punctuation mark. You should use smilies with caution in the middle of a sentence and it is always better to divide such a phrase into two more simple ones, like I have just done (...instead of final dots, because it looks strange...). But remember that a good joke should look well without any smilies :-)))))
Language particularities
Some languages have their own particularities about some of their letters. For instance, some languages have noun declension so it is quite logic to apply it to some terms like "Tkabber" itself (in case of cyrillic alphabet it is even possible to transcribe them into cyrillic, you only have to be sure that your reader will understand you). Of course, it is up to you to decide which terms (if any) should be declinable in your article, according to your language rules and taste.
Another example: Russian language has a letter "Ё" (yo) that provokes a lot of disputes about its using. Maybe there are similar cases in some other languages, so it is up to the authors or translators to maintain their language rules here in the wiki. The most important thing is not to quarrel about it and to choose some way of using such letters and then follow it.
Let's live in peace :)
Other appearance elements
- Such bullets are very handy for making lists.
- Numbered lists can also be of help (note that they can be nested like this one).
Read more about them in an article about wiki markup.
If you need to accent a vocal in a Russian or other cyrillic word do not use accented vocals from wester-european alphabets — it is incorrect. There is a special symbol of accent in Unicode — U+0301. It is written in HTML as ́ and is to be put after an "accented" vocal: Тка́ббер → Тка́ббер. Its using is explained very well in an article of Russian part of Wikipedia (unfortunately, there is no English version of that article).
If you need to "sign" some text, for example your patch you publish on our wiki, enter anywhere you need it the following:
- ~~~ (will be changed to [[Member:Wislipuzli|Wislipuzli]])
- ~~~~ (will be changed to [[Member:Wislipuzli|Wislipuzli]] HH:MM, day month year (MSD))
Do not limit yourself to the only ways of text formatting we have shown here. There is a lot of other styles displayed at Wikipedia markup page, and if you think something could serve your needs please use it without asking a permission ;) However, we would like to ask you to follow the rule of the golden mean and use styles and markup only when it is really necessary.
Sandbox
Welcome to the Sandbox if you need to check some style or HTML tag behaviour.
For translators
How to begin
To begin another language version of an article you should first edit the original slightly so that a link to a new language page appeared at the navigation menu placed at the left. Open the original article for editing and include a line like [[es:página principal (es)]] at some place (better at the beginning). The "es" prefix means the language the article will be translated into (into Spanish, in this example), and "página principal (es)" is its name in that new language. A colon placed between the prefix and the article name is not separated from both of them by spaces. Note that the suffix " (es)" should always be present, so that the wiki engine and the readers could distinguish articles that have identical names in different languages, for example "Tkabber FAQ (en)" and "Tkabber FAQ (es)". Save the article, and now you will see a new division at the bottom of the navigation menu: links to other language versions of this article. Click your link and begin to edit a new blank page. It is handy to open for editing the source article in a new tab or window of your browser, and copy&paste its source code to the new blank article. Save it just for case, then open it or a part of it again for editing and translate :)
NB: If there is more than one language versions of the article you are going to translate, do not forget to put lines [[es:página principal (es)]] into all those version pages.
Translation into mother tongue
This part is dediacted to the languages other than English. We are trying to explain the problem giving Russian terms as an example but our recommendations could be helpful for other languages too, especially if they differ from English very much, like other slavic languages, Japanese, etc.
When you translate into your own language, some problems with using specific IT terms could appear. On the one hand, in Russian IT slang there is a lot of transliterated English words like "файл" (file), "биндинг" (binding) and adapted words like "винт" (winchester, HDD), "аська" (ICQ). On the other hand, it has sense to translate some words, for example "список контактов" (a list of contacts, or just "contacts") instead of transliterated "ростер" (roster). It is up to you to decide which variant is the best, but the main recommendation is: try to avoid extremes. There is an article on our wiki named Terminology where you can look for some difficult terms and also enlarge it if you think it is necessary.
Another problem that grows when translating between languages of different language groups is loan translation, or calque. Try to avoid literal translation. If you do not understand some phrase, literal translation will not save its sense, on the contrary, it will break it. In most cases of such difficulties, it is still possible to achieve a good translation simplifying the sense of the phrase or splitting a long sentence into two or more simple ones. The last remedy: leave the source phrase next to your translation enclosed in parentheses. Somebody else will translate it later; wiki is perfect in this sense. By the way, if you read some article and see an obvious calque that spoils the discourse, do not be lazy: take a look at the source article and correct the translation. If you do not know the source language but nevertheless some place in the translation irritates you, use Discussion of that article (a link to each page's Discussion can be found at the top service menu).
Translation into a foreign language
All of us know that to do a good translation it is very important to speak fluently the destination language. In most cases, we translate into our native languages but sometimes it is necessary to translate into a foreign one. What can we advise for such cases with reference to our wiki?
- Do not translate puns and jokes that we put here and there, if you are not sure if they sound good and adequate. It is better to translate the main sense of the phrase. After all, the people comes here to look for information, not for jokes. So try to translate its information component as good as you can. But of course, if you are able to write humorously in other language, nobody will mind a good joke in your translation :)
- If there is a possibility to get a native speaker to make a proof-reading of your translation, do not miss it even if your friend knows little about Jabber and computers in general. Although the code is international, one can make mistakes, not only grammatical ones which could be forgivable, but also logical ones which is worse.
- Do not neglect spell-checkers. It is true even if you are translating into your mother tongue ;)
- Remember of the destination language syntax rules when translating the wiki articles. For example, in French, all two-element punctuation marks (colon, semicolon, exclamation and question marks, etc.) are divided from the previous word by a space. So, thanks to this particularity, there is no head-ache about setting these marks in bold.
- As a consequence from the previous advice, we would recommend not to follow the rules explained above if they go against the syntax or stylistics of the other language. It is difficult to give a good example, but if you feel that some style could not be applied (for instance, I have no idea if it is possible to apply italic to Japanese hieroglyphs), so you will have to invent another way of emphasizing some text phragment.
Menu translation
Only project administrators are able to edit the navigation menu of our wiki, so please contact Участник:bigote or Участник:lknight.
