1 |
<html> |
2 |
<head> |
3 |
<meta name="author" content="Christian Schoenebeck"> |
4 |
<title>Writing Docs</title> |
5 |
<meta name="description" content="Writing new articles for this site."> |
6 |
<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"> |
7 |
<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script> |
8 |
</head> |
9 |
<body> |
10 |
<p> |
11 |
This article provides a short introduction about how to write documents |
12 |
for this site. We appreciate any volunteers trying to help us writing |
13 |
documentation for LinuxSampler and friends. |
14 |
</p> |
15 |
|
16 |
<h3>At a Glance</h3> |
17 |
<p> |
18 |
There are plenty of documentation systems out there. Why did we need yet |
19 |
another one? Most of those systems require you to learn some kind of custom, |
20 |
exotic markup language to write documents with them. Then there are |
21 |
<i title="<u><b>W</b>hat <b>Y</b>ou <b>S</b>ee <b>I</b>s <b>W</b>hat <b>Y</b>ou <b>G</b>et:</u> A system that immediately shows you the result while creating content."> |
22 |
WYSIWG |
23 |
</i> systems which require to maintain user accounts for people who want to |
24 |
add or change content and are suffering under periodic security issues, |
25 |
which in turn require frequent software updates to avoid the site getting |
26 |
compromised. And last but not least; they don't deliver everything you |
27 |
need and are often hard to extend or to be customized. |
28 |
</p> |
29 |
<p> |
30 |
<img src="new_article.png" style="height:112px; margin-right:15px;"> |
31 |
This site is using one of the best, most flexible, and well known markup |
32 |
languages as basis for writing documents: |
33 |
<a href="http://en.wikipedia.org/wiki/HTML">HTML</a>. But obviously there |
34 |
are some caveats to use HTML as-is. Most notably it requires you to write |
35 |
a lot of monothonic, superfluous things again and again just to achieve |
36 |
simple things. And on the other hand it requires authors to invest a |
37 |
substantial amount of time learning the numerous required aspects of HTML |
38 |
and <a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets">CSS</a>. |
39 |
Fortunately; you don't have to. You don't need to have any precognition |
40 |
of HTML or CSS to write articles for this site. |
41 |
</p> |
42 |
<p> |
43 |
Here are some of the features of our documentation system in overview: |
44 |
<ul> |
45 |
<li> |
46 |
Articles are created as plain and extremely simple HTML files, which |
47 |
do not neccessarily require any previous knowledge in HTML |
48 |
(or even CSS) by article authors. |
49 |
</li> |
50 |
<li> |
51 |
The article's HTML file can immediately be previewed on the author's |
52 |
local computer by just opening it with a browser. No upload or web |
53 |
application required while creating or editing articles. |
54 |
</li> |
55 |
<li> |
56 |
Once the article is ready, it can be submitted to our server, which |
57 |
will then be filled up automatically by our software to generate our |
58 |
documentation site. The software performs all redundant work that is |
59 |
usually required to build websites with regular HTML files. This |
60 |
automatic generation supports the following features: |
61 |
<ol> |
62 |
<li> |
63 |
Automatic generation of the site's article structure. The site's |
64 |
structure can very easily be changed, by just moving around the |
65 |
article source HTML files in the article source repository. No single |
66 |
article needs to be edited for any site structure changes. |
67 |
</li> |
68 |
<li> |
69 |
Automatic correction of links and image references in articles, |
70 |
i.e. on site structure changes, trivial input errors or file type |
71 |
changes. No user interventation required. |
72 |
</li> |
73 |
<li> |
74 |
Automatic syntax highlighting of source code snippets in articles, |
75 |
so the author can concentrate simply on the content and correctness |
76 |
of his source code snippets. The software |
77 |
generates the correct look of your source code examples for you. |
78 |
</li> |
79 |
<li> |
80 |
Automatic generation of site's navigation bar, article's table of |
81 |
contents and article section IDs for the entire website. |
82 |
</li> |
83 |
<li> |
84 |
Automated generation of tooltips for links to other articles and |
85 |
technical terms or abbreviations. |
86 |
</li> |
87 |
<li> |
88 |
Automatic detection of fundamental errors in articles. Our system |
89 |
tries to correct any kind of issues automatically as much and as far |
90 |
as possible, in order to avoid bothering article authors with any kind of trivial |
91 |
things. However there are cases where it simply cannot resolve |
92 |
issues with individual articles on its own, even not by "guessing". |
93 |
In this case it will notify the author(s) about the precise problem, |
94 |
so they are aware about it and asks them to do the manual correction. |
95 |
</li> |
96 |
<li> |
97 |
This site's software is written in native C++, it generates and |
98 |
updates the entire site extremely fast. And since it is only |
99 |
updating the site's files when some input article changed, it can |
100 |
also be run as unpriviliged user and/or in a sandbox environment. |
101 |
</li> |
102 |
</ol> |
103 |
</li> |
104 |
<li> |
105 |
The site's template is a regular, static HTML file. So you can edit and |
106 |
test the site's overall look with a regular browser. No need to comment |
107 |
in/out things just for changing the general look of the site. |
108 |
</li> |
109 |
<li> |
110 |
Extensible: all articles are still real HTML after all. So you can |
111 |
easily add any kind of HTML, CSS and Java Script on your own for |
112 |
individual articles of yours if really required. So it is not neccessarily |
113 |
required to change our site's software just to add some kind of customization |
114 |
for some of your articles. |
115 |
</li> |
116 |
</ul> |
117 |
</p> |
118 |
<p> |
119 |
Enough said, let's dive in and actually see how to create an article. |
120 |
</p> |
121 |
|
122 |
<h2>A Base Article</h2> |
123 |
<p> |
124 |
Creating a new article for this site is as simple as creating a new text |
125 |
file and adding following text: |
126 |
</p> |
127 |
<code lang="html"> |
128 |
<h1>My First Article</h1> |
129 |
<p> |
130 |
This is the first paragraph. |
131 |
</p> |
132 |
</code> |
133 |
<p> |
134 |
This would already be sufficient to be a valid document and all the rest |
135 |
would automatically be added by our site's software for you. It is |
136 |
recommended though to start new documents always with following template |
137 |
instead: |
138 |
</p> |
139 |
<code> |
140 |
<html> |
141 |
<head> |
142 |
<title>??article-title??</title> |
143 |
<meta name="author" content="??author-name??"> |
144 |
<meta name="description" content="??short-description??"> |
145 |
<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"> |
146 |
<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script> |
147 |
</head> |
148 |
<body> |
149 |
<h1>??article-headline??</h1> |
150 |
<p> |
151 |
This is the first paragraph. |
152 |
</p> |
153 |
</body> |
154 |
</html> |
155 |
</code> |
156 |
<p> |
157 |
Add this to an empty text file and rename the file to a HTML file with |
158 |
arbitrary name like <code>my_first_article.html</code>. |
159 |
That template above has the advantage that you can simply open that file |
160 |
locally on your machine with your web browser and immediately preview how |
161 |
the article will look like on our website while you are writing the |
162 |
article. So you don't need to upload it somewhere for that purpose. |
163 |
</p> |
164 |
<p> |
165 |
Don't worry, you don't need to understand everything that's there. All you |
166 |
need to know is described next. |
167 |
</p> |
168 |
|
169 |
<h3>Article Short Description</h3> |
170 |
<p> |
171 |
You may provide a short description of your article with |
172 |
<code>??short-description??</code>. This is completely optional. It is used |
173 |
for example when your article is linked from another article. In that |
174 |
case the reader may i.e. move the mouse pointer over the link and a tooltip |
175 |
will popup with the document's title and the short description as summary |
176 |
of what that article is about. |
177 |
</p> |
178 |
|
179 |
<h3>Article Title</h3> |
180 |
<p> |
181 |
With <code>??article-title??</code> you provide the title of the article, |
182 |
which will be displayed in the browser's window title bar and it will also |
183 |
be displayed on our site's horizontal navigation bar, which you can find |
184 |
at the top of each page. It will also be used by our site to auto generate |
185 |
a directory structure for the generated website, thus it also has an |
186 |
impact on the final <i>URL</i> of your article. |
187 |
</p> |
188 |
<p> |
189 |
With <code>??article-headline??</code> you define the prominent headline |
190 |
shown at the very beginning of the article. |
191 |
</p> |
192 |
<p> |
193 |
In most cases <code>??article-title??</code> and |
194 |
<code>??article-headline??</code> will probably be the same text for one |
195 |
article. In that case you may also omit either one of the two. The |
196 |
software will then automatically add the missing headline or title for |
197 |
you. |
198 |
</p> |
199 |
<p> |
200 |
In some few cases you may want to have more control over the aspects of |
201 |
the article's title, its final URL path and what shall be displayed in |
202 |
the navigation bar. In this case you may use some additional optional tags |
203 |
in your document's head like this: |
204 |
</p> |
205 |
<code> |
206 |
<html> |
207 |
<head> |
208 |
<title>??article-title??</title> <!-- article's title --> |
209 |
|
210 |
<urlpath>??article-path??</urlpath> <!-- article's directory (in URL path) --> |
211 |
|
212 |
<navpath>??nav-bar-name??</navpath> <!-- article's name in navigation bar --> |
213 |
|
214 |
<meta name="author" content="John Smith"> |
215 |
<meta name="description" content="This is my first article."> |
216 |
<link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"> |
217 |
<script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script> |
218 |
</head> |
219 |
<body> |
220 |
<h1>??article-headline??</h1> |
221 |
<p> |
222 |
This is the first paragraph. |
223 |
</p> |
224 |
</body> |
225 |
</html> |
226 |
</code> |
227 |
<p> |
228 |
In this case, <code>??article-title??</code> is now only used for displaying the |
229 |
article's name in the browser's title bar and in case the reader |
230 |
bookmarks your article with his browser. |
231 |
<code>??article-path??</code> is the directory |
232 |
name where the final, generated article shall be place at. Accordingly |
233 |
this also changes the final URL to the article. And last but not least, |
234 |
<code>??nav-bar-name??</code> defines the name of your article as it shall |
235 |
be displayed on the site's navigation bar. As said, these additional tags |
236 |
are completely optional. In most cases you should be fine by just providing |
237 |
a <code><title></code> and/or <code><h1></code> with your |
238 |
article. |
239 |
</p> |
240 |
|
241 |
<h3>Article Authors</h3> |
242 |
<p> |
243 |
Also completely optional is providing <code>??author-name??</code> as |
244 |
name(s) of the person(s) who wrote the article. If you provide that information, |
245 |
then the name will be displayed in the footer section of the article on |
246 |
our site. Don't be shy and add your name to get credited for your work. |
247 |
If you change an already existing article, you may simply add your name |
248 |
by adding a comma like so: |
249 |
</p> |
250 |
<code> |
251 |
<meta name="author" content="John Doe, Bob Fox, Mary Smith"> |
252 |
</code> |
253 |
<p> |
254 |
The author information may also be useful for people to contact the person |
255 |
who wrote the original article in order to ask some questions about it. |
256 |
</p> |
257 |
|
258 |
<h2>Headlines</h2> |
259 |
<p> |
260 |
All headlines in your article are defined with regular HTML headline |
261 |
tags. The following three headline types are available: |
262 |
</p> |
263 |
<ol> |
264 |
<li><code><h1>??article-headline??</h1></code> Like described in the |
265 |
previous section, a <code><h1></code> headline is the most prominent |
266 |
headline of your article. It should only be used once; at the very |
267 |
beginning of your article to display the general topic of the article. |
268 |
</li> |
269 |
<li><code><h2>??sub-headline??</h2></code> This headline type is a bit |
270 |
less prominent than a <code><h1></code> headline. You may use |
271 |
<code><h2></code> headlines to introduce important sections |
272 |
of your article. |
273 |
</li> |
274 |
<li><code><h3>??sub-sub-headline??</h3></code> This is the least |
275 |
prominent headline type. You may use it to further subdivide your |
276 |
article in smaller sections. |
277 |
</li> |
278 |
</ol> |
279 |
<p> |
280 |
This is the corresponding look for each one of the three headline types: |
281 |
</p> |
282 |
<example> |
283 |
<h1>This is a <h1> headline</h1> |
284 |
<h2>This is a <h2> headline</h2> |
285 |
<h3>This is a <h3> headline</h3> |
286 |
</example> |
287 |
<p> |
288 |
It's completely up to you which one of those three headline types to use, |
289 |
how often you use them and where. All of them will be taken by the site's |
290 |
software to automatically generate a table of content of your Article, |
291 |
which will be shown at the left side next to your article on our site. |
292 |
</p> |
293 |
<p> |
294 |
Once your article is |
295 |
<a href="02_uploading_docs.html">uploaded to our site</a>, IDs for the individual |
296 |
headlines will automatically be generated for you. If for example you had |
297 |
somewhere in your article a headline called "Conclusion of Topic", then |
298 |
this particular paragraph of your article may be directly linked to from |
299 |
other articles or other sites with an URL like |
300 |
<code lang="none">http://doc.linuxsampler.org/path/to/your/article/#conclusion_of_topic</code>. |
301 |
If you want to override this behavior, because you rather want to use your |
302 |
own ID for a paragraph of your article, then simply set the desired ID with |
303 |
your headline: |
304 |
</p> |
305 |
<code lang="html"> |
306 |
<h3 id="my_conclusion">Conclusion of topic</h3> |
307 |
</code> |
308 |
|
309 |
<h2>Paragraphs</h2> |
310 |
<p> |
311 |
You should wrap each continous text block of your article in between |
312 |
a paragraph tag pair like: |
313 |
</p> |
314 |
<code> |
315 |
<p> |
316 |
This is a paragraph. All the text in a paragraph is combined to one continous |
317 |
text block. You may add as much text as you want to a paragraph of your article, |
318 |
but better separate you article into logical parts of separate paragraphs. So to start a |
319 |
new paragraph, wrap the next text block into a new pair of paragraph tags. |
320 |
</p> |
321 |
<p> |
322 |
This is the next paragraph. There will be an empty line between this paragraph and |
323 |
the previous and next paragraph, to separate paragraphs visually from each other. |
324 |
</p> |
325 |
</code> |
326 |
<p> |
327 |
Which would look like: |
328 |
</p> |
329 |
<example> |
330 |
<p> |
331 |
This is a paragraph. All the text in a paragraph is combined to one continous |
332 |
text block. You may add as much text as you want to a paragraph of your article, |
333 |
but better separate you article into logical parts of separate paragraphs. So to start a |
334 |
new paragraph, wrap the next text block into a new pair of paragraph tags. |
335 |
</p> |
336 |
<p> |
337 |
This is the next paragraph. There will be an empty line between this paragraph and |
338 |
the previous and next paragraph, to separate paragraphs visually from each other. |
339 |
</p> |
340 |
</example> |
341 |
<p> |
342 |
Wrapping paragraphs into <code><p>??text??</p></code> blocks not only causes |
343 |
trivial new lines in between them. This construct also allows you to easily |
344 |
define whether certain additional content like images and source code |
345 |
examples shall be shown directly embedded within the text block or shall |
346 |
rather be shown separately outside of text blocks, like described next. |
347 |
</p> |
348 |
|
349 |
<h2>Pictures</h2> |
350 |
<p> |
351 |
To display i.e. screen shots, figures and other kinds of images in your |
352 |
article, simply place the picture file in the directory where your |
353 |
current article's file is located at. Then add the image to your article |
354 |
with an <code><img src="some_picture.png"></code> HTML tag. There are two |
355 |
distinct ways to do that, like described below. |
356 |
</p> |
357 |
<h3>Stand-Alone Pictures</h3> |
358 |
<p> |
359 |
To place a picture on |
360 |
its own between two text paragraphs, simply place the <code><img></code> |
361 |
tag between the two paragraphs in your HTML file: |
362 |
</p> |
363 |
<code> |
364 |
<p> |
365 |
This is the first paragraph. Just before the picture. |
366 |
</p> |
367 |
|
368 |
<img src="some_picture.png" caption="??footnote??" title="??tooltip-text??"> |
369 |
|
370 |
<p> |
371 |
This is the next paragraph, just after the picture. |
372 |
</p> |
373 |
</code> |
374 |
<p> |
375 |
The optional <code>??footnote??</code> adds a footnote text just below the |
376 |
image and the optional <code>??tooltip-text??</code> defines a text which |
377 |
will popup if the reader points his mouse over the image. The previous |
378 |
example would look like this: |
379 |
</p> |
380 |
<example> |
381 |
<p> |
382 |
This is the first paragraph. Just before the picture. |
383 |
</p> |
384 |
<img src="a_picture.png" caption="Some Explanation" title="A tooltip text"> |
385 |
<p> |
386 |
This is the next paragraph, just after the picture. |
387 |
</p> |
388 |
</example> |
389 |
<p> |
390 |
You also don't have to worry about the size of the image. If the image |
391 |
resolution is larger than the width of the article would currently require |
392 |
on the user's screen, then the image will automatically be downscaled to |
393 |
fit the width of the article. It is recommended though to keep the width |
394 |
of images approximately below 1200px, just to not waste too much repository space |
395 |
(that is disk space) and network bandwidth. |
396 |
</p> |
397 |
|
398 |
<h3>Embedded Pictures</h3> |
399 |
<p> |
400 |
Sometimes however it looks nicer to have a picture embedded directly inside a |
401 |
paragraph of text and let that text float around that picture, especially |
402 |
when using rather small images. To achieve that, simply place the image |
403 |
tag inside the paragraph of your HTML file like: |
404 |
</p> |
405 |
<code> |
406 |
<p> |
407 |
<img src="some_picture.png"> |
408 |
This is some text of a paragraph. In this particular case, this text will |
409 |
float around the picture. The rest of this text is just repeating, |
410 |
repeating, repeating, repeating, repeating, repeating, repeating, |
411 |
repeating, repeating, repeating, repeating, repeating, repeating, |
412 |
repeating, repeating, repeating, repeating, repeating, repeating, |
413 |
repeating, repeating, repeating, repeating, repeating, repeating, |
414 |
repeating, repeating, repeating, repeating, repeating, repeating, |
415 |
repeating, repeating, repeating, repeating, repeating, repeating, |
416 |
repeating, repeating, repeating, repeating, repeating, repeating, |
417 |
repeating, repeating, repeating, repeating, repeating, repeating, |
418 |
repeating, repeating, repeating, repeating, repeating, repeating. |
419 |
</p> |
420 |
</code> |
421 |
<p> |
422 |
Which would look like this: |
423 |
</p> |
424 |
<example style="clear:both;"> |
425 |
<p> |
426 |
<img src="a_picture.png"> |
427 |
This is some text of a paragraph. In this particular case, this text will |
428 |
float around the picture. The rest of this text is just repeating, |
429 |
repeating, repeating, repeating, repeating, repeating, repeating, |
430 |
repeating, repeating, repeating, repeating, repeating, repeating, |
431 |
repeating, repeating, repeating, repeating, repeating, repeating, |
432 |
repeating, repeating, repeating, repeating, repeating, repeating, |
433 |
repeating, repeating, repeating, repeating, repeating, repeating, |
434 |
repeating, repeating, repeating, repeating, repeating, repeating, |
435 |
repeating, repeating, repeating, repeating, repeating, repeating, |
436 |
repeating, repeating, repeating, repeating, repeating, repeating, |
437 |
repeating, repeating, repeating, repeating, repeating, repeating. |
438 |
</p> |
439 |
</example> |
440 |
<p> |
441 |
As you can see, no special knowledge in i.e. HTML or CSS required to achieve |
442 |
such things very easily. |
443 |
</p> |
444 |
|
445 |
<h3>Unique Pictures</h3> |
446 |
<p> |
447 |
Once your article and its picture(s) are |
448 |
<a href="02_uploading_docs.html">uploaded to our server</a>, our |
449 |
system will automatically check that all images on our entire site have |
450 |
unique and unambiguous file names, no matter at which directory they |
451 |
are stored to exactly. The "file name" that is checked in this case, is |
452 |
actually the picture's file name without its file type extension |
453 |
(i.e. without ".png", ".jpg", ".gif", etc. at its end). There are two reasons for this: |
454 |
<ol> |
455 |
<li><b>Site Structure Changes:</b> |
456 |
After a while, the structure on a website changes. Certain articles |
457 |
are moved to completely different directories and some article's may |
458 |
reference pictures that were already added and used by other articles before. |
459 |
Which makes sense of course, why saving the exact same picture 10 times |
460 |
under different image files if you can just reference that already existing image file from your new article? |
461 |
Now when those articles and/or the images move to different locations, |
462 |
the image references within such articles might turn to dead references. |
463 |
Our system automatically detects this and corrects the references in |
464 |
articles to any kind of image file automatically, without requiring |
465 |
any user intervention. So we can change the structure of the website |
466 |
at any time without having to update any article file. |
467 |
</li> |
468 |
<li><b>File Type Changes:</b> |
469 |
Sometimes it happens that a picture needs to be replaced with a |
470 |
picture in a different file format. For example the original picture |
471 |
was added in .jpeg format to have a very small file size, but later on |
472 |
some kind of transparency is required for the picture, which is not |
473 |
supported by JPEG. In this case the picture would i.e. be updated |
474 |
and replaced with a .png image file. Our system also detects this and |
475 |
automatically updates all references to that image file in all articles |
476 |
to the precise new name of the image file. Again, no user intervention |
477 |
required. |
478 |
</li> |
479 |
</ol> |
480 |
But for the system to be able to that automatically, it requires all |
481 |
image files to have unique file names, like described above. If you try |
482 |
to upload a new image file to our system which uses a file name that was |
483 |
already taken by another image, then you will automatically be notified by |
484 |
our system via email, asking you to rename one of the image files. |
485 |
</p> |
486 |
|
487 |
<h2>Source Code</h2> |
488 |
<p> |
489 |
You might need to post example source code in some of your articles. This |
490 |
is very simple to do. Just wrap your source code into a pair of |
491 |
<code><code></code> tags like this: |
492 |
</p> |
493 |
<code> |
494 |
<code lang="??language??"> |
495 |
|
496 |
??source-code?? |
497 |
|
498 |
</code> |
499 |
</code> |
500 |
<p> |
501 |
Syntax highlighting is automatically generated for you. That way you don't |
502 |
have to waste time on how to display source code nicely, and rather |
503 |
concentrate on the content of your article instead. |
504 |
You should provide the intended programming language of your source code sample |
505 |
with <code>??language??</code>. |
506 |
Obviously it is exhausting to supply such a <code lang="none">lang</code> |
507 |
attribute with every single code sample, especially if you are just referring |
508 |
to a single code token within your paragraphs. So you don't have to do that. |
509 |
If you omit the <code lang="none">lang</code> attribute, then our site's |
510 |
software will automatically use the language defined by you with one of |
511 |
the previous code blocks. You may also disable automatic syntax highlighting |
512 |
with <code lang="html"><code lang="none"></code>, which will cause |
513 |
that code block to appear simply in monochrome color. |
514 |
</p> |
515 |
<p> |
516 |
Like with images, you can |
517 |
decide in which context the source code shall appear in your article, |
518 |
as described next. |
519 |
</p> |
520 |
|
521 |
<note> |
522 |
Automatic syntax highlighting is currently available for the |
523 |
<ul> |
524 |
<li><a href="nksp.html">NKSP real-time instrument script language</a></li> |
525 |
<li>HTML markup language</li> |
526 |
</ul> |
527 |
If you need another source code language, just tell |
528 |
<a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
529 |
and he will add the required module for any kind of language |
530 |
(even the most exotic one) on our server in short time. |
531 |
</note> |
532 |
|
533 |
<h3>Stand-Alone Code</h3> |
534 |
<p> |
535 |
If you put your code block outside of paragraphs, that is between |
536 |
paragraph blocks in your HTML file, then the source code will also appear |
537 |
on its own between the paragraph blocks. Here is an example for the |
538 |
<a href="nksp.html">NKSP script language</a>. |
539 |
</p> |
540 |
<code lang="html"> |
541 |
<p> |
542 |
Paragraph just before the source code block. |
543 |
</p> |
544 |
<code lang="nksp"> |
545 |
on init |
546 |
@foo := "A message" |
547 |
message(@foo) |
548 |
end on |
549 |
</code> |
550 |
<p> |
551 |
Next paragraph just after the source code block. |
552 |
</p> |
553 |
</code> |
554 |
<p> |
555 |
Which would appear like: |
556 |
</p> |
557 |
<example> |
558 |
<p> |
559 |
Paragraph just before the source code block. |
560 |
</p> |
561 |
<code lang="nksp"> |
562 |
on init |
563 |
@foo := "A message" |
564 |
message(@foo) |
565 |
end on |
566 |
</code> |
567 |
<p> |
568 |
Next paragraph just after the source code block. |
569 |
</p> |
570 |
</example> |
571 |
<p> |
572 |
The source code automatically appears nicely in color and with line |
573 |
numbers between the two paragraphs. This site's software will also take |
574 |
care about removing white lines at the front and end of your source code |
575 |
blocks appropriately. |
576 |
</p> |
577 |
|
578 |
<h3>Embedded Code</h3> |
579 |
<p> |
580 |
In case you are mentioning a very small part of the source code in your |
581 |
text, then you probably might want that to be displayed actually as source code |
582 |
directly embedded into your paragraph. You might already guess how to |
583 |
do that: simply put the code block into the paragraph text block of your |
584 |
HTML file: |
585 |
</p> |
586 |
<code lang="html"> |
587 |
<p> |
588 |
A variable is assigned with NKSP like this <code>$foo := 5</code>, in this |
589 |
case you are assigning <code>5</code> to the integer variable <code>$foo</code>. |
590 |
</p> |
591 |
</code> |
592 |
<p> |
593 |
And this would be the result: |
594 |
</p> |
595 |
<example> |
596 |
<p> |
597 |
A variable is assigned with NKSP like this <code lang="nksp">$foo := 5</code>, in this |
598 |
case you are assigning <code lang="nksp">5</code> to the integer variable <code lang="nksp">$foo</code>. |
599 |
</p> |
600 |
</example> |
601 |
<p> |
602 |
That looks now much more easier to read, doesn't it? |
603 |
</p> |
604 |
|
605 |
<note> |
606 |
Syntax highlighting of source code is automatically generated by our site's software |
607 |
once the document is |
608 |
<a href="02_uploading_docs.html">uploaded to our server</a>. |
609 |
So when you are just |
610 |
previewing your article with source code snippets on your local machine, |
611 |
then those source code snippets will yet be displayed monochrome, |
612 |
without any syntax highlighting. |
613 |
</note> |
614 |
|
615 |
<h3>Metaphors</h3> |
616 |
<p> |
617 |
You might have noticed, we have used a special kind of <code lang="html">??place-holder??</code> for |
618 |
human-readable portions in source code before, which shall outline to the reader |
619 |
that it is not actually "real" source code, but just reflecting its semantic meaning. |
620 |
Simply put the respective pseudo-code into a pair of two question marks, |
621 |
like so: |
622 |
</p> |
623 |
<code lang="html"> |
624 |
<code> |
625 |
on init |
626 |
declare const $i = \?\?some-value\?\? |
627 |
|
628 |
message(\?\?text-string\?\?) |
629 |
end on |
630 |
</code> |
631 |
</code> |
632 |
<p> |
633 |
Which will look like this: |
634 |
</p> |
635 |
<example> |
636 |
<code lang="nksp"> |
637 |
on init |
638 |
declare const $i = ??some-value?? |
639 |
|
640 |
message(??text-string??) |
641 |
end on |
642 |
</code> |
643 |
</example> |
644 |
<p> |
645 |
These <i>metaphors</i> are especially useful in beginners tutorials for |
646 |
clearly separating real source code portions from pseudo-code portions, |
647 |
and to point the reader's eyes to the most important locations of your |
648 |
source code snippet. |
649 |
</p> |
650 |
|
651 |
<h2>Links and Article File Names</h2> |
652 |
<p> |
653 |
If you want to add links in your article to another article or to some |
654 |
other website, then you just use an ordinary HTML link tag pair: |
655 |
</p> |
656 |
<code lang="html"> |
657 |
<p> |
658 |
This paragraph contains <a href="../nksp.html">a link to another article</a> |
659 |
and to <a href="http://www.linuxsampler.org">another website</a>. |
660 |
</p> |
661 |
</code> |
662 |
<example> |
663 |
<p> |
664 |
This paragraph contains <a href="../nksp.html">a link to another article</a> |
665 |
and to <a href="http://www.linuxsampler.org">another website</a>. |
666 |
</p> |
667 |
</example> |
668 |
<p> |
669 |
Concerning links to other websites, there is nothing special for you to know about. |
670 |
</p> |
671 |
<p> |
672 |
Regarding local links to another article however: these are monitored |
673 |
similar like references to image files (as <a href="#unique_pictures">described before</a>), that is |
674 |
our system automatically detects if the path of some of your local links to |
675 |
another article is incorrect, i.e. because the website structure changed |
676 |
in the meantime, and it will automatically correct the path to the correct |
677 |
location of the article for you, without requiring any user intervention. |
678 |
For this reason, all articles must have unique file names for the entire |
679 |
site, no matter in which directory the respective article's HTML file is |
680 |
located at exactly. |
681 |
</p> |
682 |
<p> |
683 |
An article file on our site usually has the following |
684 |
file name form: |
685 |
</p> |
686 |
<code lang="none"> |
687 |
??number-prefix??_??unique-name??.html |
688 |
</code> |
689 |
<p> |
690 |
The <code>??number-prefix??</code> is optional. It allows us to control |
691 |
the order of articles on the same website structure level (i.e. |
692 |
concerning its location in the navigation bar). |
693 |
The <code>??unique-name??</code> portion of the file name though is actually the |
694 |
relevant part our site's software is looking at. This "root" of its file |
695 |
name must be globally unique among our entire site. If you add a new |
696 |
article to our site with a file name that is already taken by another |
697 |
article, then our system will automatically inform you via email to |
698 |
resolve this issue by renaming one of them. Also note that the file name |
699 |
just acts as internal ID while writing articles. The original file name |
700 |
of the input HTML file will not be directly exposed to readers on our |
701 |
documentation site. |
702 |
</p> |
703 |
|
704 |
<h2>Terms</h2> |
705 |
<p> |
706 |
Technical terms and abbreviations are often used in articles to reduce |
707 |
the amount of text for transmitting some kind of information about a |
708 |
certain topic to the reader. You might want to emphasize technical terms and abbreviations |
709 |
in your article, by wrapping the term into a pair of <code lang="html"><i></code> HTML |
710 |
tags. On our site this will not only show the term in a special unified |
711 |
font style (currently italic), but it allows you also to define the |
712 |
meaning of the term <b>once</b>. Which goes like this: |
713 |
</p> |
714 |
|
715 |
<h3>Defining a Term</h3> |
716 |
<p> |
717 |
You may define a new term like this: |
718 |
</p> |
719 |
<code lang="html"> |
720 |
<p> |
721 |
He left the bar and jumped right into his |
722 |
<i title="A very large vehicle.">Mega Liner</i> |
723 |
to follow the street right into sunset. |
724 |
</p> |
725 |
</code> |
726 |
<example> |
727 |
<p> |
728 |
He left the bar and jumped right into his |
729 |
<i title="A very large truck vehicle.">Mega Liner</i> |
730 |
to follow the street right into sunset. |
731 |
</p> |
732 |
</example> |
733 |
<p> |
734 |
Now when you point your mouse over the term, a popup will appear, |
735 |
describing the meaning of the term. |
736 |
</p> |
737 |
|
738 |
<h3>Referencing an already defined Term</h3> |
739 |
<p> |
740 |
Obviously you don't want to define |
741 |
the same term over and over again, just to provide the user the meaning of |
742 |
it at any occurence of the site. That's why our software does that |
743 |
automatically for you once your article is |
744 |
<a href="02_uploading_docs.html">uploaded to our server</a>. |
745 |
Now when you use the term at another place, i.e. in another article, then |
746 |
it will automatically have the same meaning attached to it: |
747 |
</p> |
748 |
<code> |
749 |
<p> |
750 |
Once again he was sitting behind the wheel of his <i>Mega Liner</i>, |
751 |
but things were different back then. |
752 |
</p> |
753 |
</code> |
754 |
<example> |
755 |
<p> |
756 |
Once again he was sitting behind the wheel of his <i>Mega Liner</i>, but |
757 |
things were different back then. |
758 |
</p> |
759 |
</example> |
760 |
<p> |
761 |
Point your mouse again over the term, and you will notice that the same |
762 |
term definition will popup as tooltip, like at its original location where |
763 |
it was defined before. |
764 |
<p> |
765 |
</p> |
766 |
Due to this fact, our site's software does not even allow you to define the |
767 |
same term more than once (at least not with a different meaning that is). |
768 |
It will scan all documents in our current pool and if somebody tries to |
769 |
re-declare an already existing term again with a different meaning, he |
770 |
will automatically be notified by our system via email and kindly asked |
771 |
to resolve the ambiguousness. |
772 |
</p> |
773 |
<note> |
774 |
Our system automatically handles redundant variants of terms. That means |
775 |
first of all, that all term names are stored, compared and looked up case insensitive, |
776 |
and the system automatically tries to auto complete i.e. plural forms |
777 |
of the same term. |
778 |
</note> |
779 |
|
780 |
<h2>Tables</h2> |
781 |
<p> |
782 |
Tables are written like ordinary HTML tables. That is: |
783 |
</p> |
784 |
<code> |
785 |
<table> |
786 |
<tr> |
787 |
<th>Name</th> <th>Description</th> |
788 |
</tr> |
789 |
<tr> |
790 |
<td>Foo</td> <td>Some text.</td> |
791 |
</tr> |
792 |
<tr> |
793 |
<td>Bar</td> <td>And more text.</td> |
794 |
</tr> |
795 |
<tr> |
796 |
<td>Thing</td> <td>And that's it.</td> |
797 |
</tr> |
798 |
</table> |
799 |
</code> |
800 |
<example> |
801 |
<table> |
802 |
<tr> |
803 |
<th>Name</th> <th>Description</th> |
804 |
</tr> |
805 |
<tr> |
806 |
<td>Foo</td> <td>Some text.</td> |
807 |
</tr> |
808 |
<tr> |
809 |
<td>Bar</td> <td>And more text.</td> |
810 |
</tr> |
811 |
<tr> |
812 |
<td>Thing</td> <td>And that's it.</td> |
813 |
</tr> |
814 |
</table> |
815 |
</example> |
816 |
<p> |
817 |
So <code><tr></code> wraps up individual rows of a table, |
818 |
<code><th></code> contains the individual cells of the table header, |
819 |
and <code><td></code> contains the individual cells of the table's |
820 |
body. |
821 |
</p> |
822 |
|
823 |
<h2>Note Boxes</h2> |
824 |
<p> |
825 |
Once in a while you need to inform the reader about noteworthy issues. |
826 |
For this purpose we are using a special <code><note></code> tag. |
827 |
</p> |
828 |
<h3>Regular Notes</h3> |
829 |
<p> |
830 |
To add regular notes to your article with low or normal importance, add |
831 |
the note like this: |
832 |
</p> |
833 |
<code> |
834 |
<note> |
835 |
This is an issue you need to know about. Please read this carefully to avoid |
836 |
making any mistakes. |
837 |
</note> |
838 |
</code> |
839 |
<example> |
840 |
<note> |
841 |
This is an issue you need to know about. Please read this carefully to avoid |
842 |
making any mistakes. |
843 |
</note> |
844 |
</example> |
845 |
<p> |
846 |
This is not a regular HTML tag defined in the HTML standard, but with |
847 |
modern browsers supporting CSS3, it should display just as intended. |
848 |
</p> |
849 |
|
850 |
<h3>Important Notes</h3> |
851 |
<p> |
852 |
If you need to inform the reader about a very important issue instead, |
853 |
then you might use the following slightly different form: |
854 |
</p> |
855 |
<code> |
856 |
<note class="important"> |
857 |
Now this is a very important issue you need to be aware of. If you ignore it, |
858 |
your task will fail. |
859 |
</note> |
860 |
</code> |
861 |
<example> |
862 |
<note class="important"> |
863 |
Now this is a very important issue you need to be aware of. If you ignore it, |
864 |
your task will fail. |
865 |
</note> |
866 |
</example> |
867 |
<p> |
868 |
The only thing that changed compared to the regular note, is the "class" |
869 |
attribute of the note tag. |
870 |
</p> |
871 |
|
872 |
<h2>Directory Listings</h2> |
873 |
<p> |
874 |
Software components often have a certain kind of directory structure. |
875 |
For readers of your articles is it way easier to perceive directory |
876 |
structures if they are displayed in a visual appropriate way. There are |
877 |
two specials tags you can use for this purpose: |
878 |
</p> |
879 |
<code lang="html"> |
880 |
<dir>/ |
881 |
<dir>home |
882 |
<dir>bob |
883 |
<file>README.txt</file> |
884 |
<file>foo.sh</file> |
885 |
</dir> |
886 |
</dir> |
887 |
<dir>tmp |
888 |
<file>bla.tmp</file> |
889 |
</dir> |
890 |
</dir> |
891 |
</code> |
892 |
<example> |
893 |
<dir>/ |
894 |
<dir>home |
895 |
<dir>bob |
896 |
<file>README.txt</file> |
897 |
<file>foo.sh</file> |
898 |
</dir> |
899 |
</dir> |
900 |
<dir>tmp |
901 |
<file>bla.tmp</file> |
902 |
</dir> |
903 |
</dir> |
904 |
</example> |
905 |
<p> |
906 |
Currently for each file the same icon will be displayed. This might change |
907 |
in future, i.e. a an automatic different icon could be picked by the |
908 |
site's software according to the respective file name extension. |
909 |
</p> |
910 |
|
911 |
<h2>Extensions</h2> |
912 |
<p> |
913 |
This is almost the end of this article. You are still seeking for features |
914 |
for one of your articles, that are not already covered by our system? |
915 |
Then either ask <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
916 |
whether that feature could be added, or ... extend your article on your |
917 |
own. It's real HTML after all! So you can add your own HTML, CSS and |
918 |
Java Script to your articles at any time! |
919 |
</p> |
920 |
|
921 |
<h2>What next?</h2> |
922 |
<p> |
923 |
You are at the end of our tour introducing our documentation system. |
924 |
You may now start writing your first article. Once you are done with it, |
925 |
simply |
926 |
<a href="http://www.linuxsampler.org/developers.html">send your article to some of us</a>, |
927 |
or request an account to our Subversion repository, so you can |
928 |
manage articles of our documentation site on your own. |
929 |
</p> |
930 |
<p> |
931 |
You already got a Subversion account? Then continue reading |
932 |
<a href="02_uploading_docs.html">how to upload articles</a> for this site. |
933 |
</p> |
934 |
<p> |
935 |
Thanks for your support! |
936 |
</p> |
937 |
|
938 |
</body> |
939 |
</html> |