/[svn]/doc/docbase/writing_docs/01_writing_docs.html
ViewVC logotype

Contents of /doc/docbase/writing_docs/01_writing_docs.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3083 - (show annotations) (download) (as text)
Mon Jan 9 19:23:58 2017 UTC (7 years, 2 months ago) by schoenebeck
File MIME type: text/html
File size: 38987 byte(s)
* Added SFZ articles section.
* NKSP: New sfz "script" opcode added.

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 &lt;html&gt;
141 &lt;head&gt;
142 &lt;title>??article-title??&lt;/title&gt;
143 &lt;meta name="author" content="??author-name??"&gt;
144 &lt;meta name="description" content="??short-description??"&gt;
145 &lt;link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"&gt;
146 &lt;script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"&gt;&lt;/script&gt;
147 &lt;/head&gt;
148 &lt;body&gt;
149 <h1>??article-headline??</h1>
150 <p>
151 This is the first paragraph.
152 </p>
153 &lt;/body&gt;
154 &lt;/html&gt;
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 &lt;html&gt;
207 &lt;head&gt;
208 &lt;title>??article-title??&lt;/title&gt; <!-- article's title -->
209
210 &lt;urlpath>??article-path??&lt;/urlpath&gt; <!-- article's directory (in URL path) -->
211
212 &lt;navpath>??nav-bar-name??&lt;/navpath&gt; <!-- article's name in navigation bar -->
213
214 &lt;meta name="author" content="John Smith"&gt;
215 &lt;meta name="description" content="This is my first article."&gt;
216 &lt;link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css"&gt;
217 &lt;script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"&gt;&lt;/script&gt;
218 &lt;/head&gt;
219 &lt;body&gt;
220 <h1>??article-headline??</h1>
221 <p>
222 This is the first paragraph.
223 </p>
224 &lt;/body&gt;
225 &lt;/html&gt;
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>&lt;title&gt;</code> and/or <code>&lt;h1&gt;</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 &lt;meta name="author" content="John Doe, Bob Fox, Mary Smith"&gt;
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 &lt;h1&gt; headline</h1>
284 <h2>This is a &lt;h2&gt; headline</h2>
285 <h3>This is a &lt;h3&gt; 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 &lt;img src="some_picture.png" caption="??footnote??" title="??tooltip-text??"&gt;
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>&lt;code&gt;</code> tags like this:
492 </p>
493 <code>
494 &lt;code lang="??language??"&gt;
495
496 ??source-code??
497
498 &lt;/code&gt;
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">&lt;code lang="none"&gt;</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 <li><a href="sfz.html">SFZ File Format</a></li>
527 </ul>
528 If you need another source code language, just tell
529 <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>
530 and he will add the required module for any kind of language
531 (even the most exotic one) on our server in short time.
532 </note>
533
534 <h3>Stand-Alone Code</h3>
535 <p>
536 If you put your code block outside of paragraphs, that is between
537 paragraph blocks in your HTML file, then the source code will also appear
538 on its own between the paragraph blocks. Here is an example for the
539 <a href="nksp.html">NKSP script language</a>.
540 </p>
541 <code lang="html">
542 <p>
543 Paragraph just before the source code block.
544 </p>
545 &lt;code lang="nksp"&gt;
546 on init
547 @foo := "A message"
548 message(@foo)
549 end on
550 &lt;/code&gt;
551 <p>
552 Next paragraph just after the source code block.
553 </p>
554 </code>
555 <p>
556 Which would appear like:
557 </p>
558 <example>
559 <p>
560 Paragraph just before the source code block.
561 </p>
562 <code lang="nksp">
563 on init
564 @foo := "A message"
565 message(@foo)
566 end on
567 </code>
568 <p>
569 Next paragraph just after the source code block.
570 </p>
571 </example>
572 <p>
573 The source code automatically appears nicely in color and with line
574 numbers between the two paragraphs. This site's software will also take
575 care about removing white lines at the front and end of your source code
576 blocks appropriately.
577 </p>
578
579 <h3>Embedded Code</h3>
580 <p>
581 In case you are mentioning a very small part of the source code in your
582 text, then you probably might want that to be displayed actually as source code
583 directly embedded into your paragraph. You might already guess how to
584 do that: simply put the code block into the paragraph text block of your
585 HTML file:
586 </p>
587 <code lang="html">
588 <p>
589 A variable is assigned with NKSP like this &lt;code&gt;$foo := 5&lt;/code&gt;, in this
590 case you are assigning &lt;code&gt;5&lt;/code&gt; to the integer variable &lt;code&gt;$foo&lt;/code&gt;.
591 </p>
592 </code>
593 <p>
594 And this would be the result:
595 </p>
596 <example>
597 <p>
598 A variable is assigned with NKSP like this <code lang="nksp">$foo := 5</code>, in this
599 case you are assigning <code lang="nksp">5</code> to the integer variable <code lang="nksp">$foo</code>.
600 </p>
601 </example>
602 <p>
603 That looks now much more easier to read, doesn't it?
604 </p>
605
606 <note>
607 Syntax highlighting of source code is automatically generated by our site's software
608 once the document is
609 <a href="02_uploading_docs.html">uploaded to our server</a>.
610 So when you are just
611 previewing your article with source code snippets on your local machine,
612 then those source code snippets will yet be displayed monochrome,
613 without any syntax highlighting.
614 </note>
615
616 <h3>Metaphors</h3>
617 <p>
618 You might have noticed, we have used a special kind of <code lang="html">??place-holder??</code> for
619 human-readable portions in source code before, which shall outline to the reader
620 that it is not actually "real" source code, but just reflecting its semantic meaning.
621 Simply put the respective pseudo-code into a pair of two question marks,
622 like so:
623 </p>
624 <code lang="html">
625 &lt;code&gt;
626 on init
627 declare const $i = \?\?some-value\?\?
628
629 message(\?\?text-string\?\?)
630 end on
631 &lt;/code&gt;
632 </code>
633 <p>
634 Which will look like this:
635 </p>
636 <example>
637 <code lang="nksp">
638 on init
639 declare const $i = ??some-value??
640
641 message(??text-string??)
642 end on
643 </code>
644 </example>
645 <p>
646 These <i>metaphors</i> are especially useful in beginners tutorials for
647 clearly separating real source code portions from pseudo-code portions,
648 and to point the reader's eyes to the most important locations of your
649 source code snippet.
650 </p>
651
652 <h2>Links and Article File Names</h2>
653 <p>
654 If you want to add links in your article to another article or to some
655 other website, then you just use an ordinary HTML link tag pair:
656 </p>
657 <code lang="html">
658 <p>
659 This paragraph contains &lt;a href="../nksp.html"&gt;a link to another article&lt;/a&gt;
660 and to &lt;a href="http://www.linuxsampler.org"&gt;another website&lt;/a&gt;.
661 </p>
662 </code>
663 <example>
664 <p>
665 This paragraph contains <a href="../nksp.html">a link to another article</a>
666 and to <a href="http://www.linuxsampler.org">another website</a>.
667 </p>
668 </example>
669 <p>
670 Concerning links to other websites, there is nothing special for you to know about.
671 </p>
672 <p>
673 Regarding local links to another article however: these are monitored
674 similar like references to image files (as <a href="#unique_pictures">described before</a>), that is
675 our system automatically detects if the path of some of your local links to
676 another article is incorrect, i.e. because the website structure changed
677 in the meantime, and it will automatically correct the path to the correct
678 location of the article for you, without requiring any user intervention.
679 For this reason, all articles must have unique file names for the entire
680 site, no matter in which directory the respective article's HTML file is
681 located at exactly.
682 </p>
683 <p>
684 An article file on our site usually has the following
685 file name form:
686 </p>
687 <code lang="none">
688 ??number-prefix??_??unique-name??.html
689 </code>
690 <p>
691 The <code>??number-prefix??</code> is optional. It allows us to control
692 the order of articles on the same website structure level (i.e.
693 concerning its location in the navigation bar).
694 The <code>??unique-name??</code> portion of the file name though is actually the
695 relevant part our site's software is looking at. This "root" of its file
696 name must be globally unique among our entire site. If you add a new
697 article to our site with a file name that is already taken by another
698 article, then our system will automatically inform you via email to
699 resolve this issue by renaming one of them. Also note that the file name
700 just acts as internal ID while writing articles. The original file name
701 of the input HTML file will not be directly exposed to readers on our
702 documentation site.
703 </p>
704
705 <h2>Terms</h2>
706 <p>
707 Technical terms and abbreviations are often used in articles to reduce
708 the amount of text for transmitting some kind of information about a
709 certain topic to the reader. You might want to emphasize technical terms and abbreviations
710 in your article, by wrapping the term into a pair of <code lang="html"><i></code> HTML
711 tags. On our site this will not only show the term in a special unified
712 font style (currently italic), but it allows you also to define the
713 meaning of the term <b>once</b>. Which goes like this:
714 </p>
715
716 <h3>Defining a Term</h3>
717 <p>
718 You may define a new term like this:
719 </p>
720 <code lang="html">
721 <p>
722 He left the bar and jumped right into his
723 &lt;i title="A very large vehicle."&gt;Mega Liner&lt;/i&gt;
724 to follow the street right into sunset.
725 </p>
726 </code>
727 <example>
728 <p>
729 He left the bar and jumped right into his
730 <i title="A very large truck vehicle.">Mega Liner</i>
731 to follow the street right into sunset.
732 </p>
733 </example>
734 <p>
735 Now when you point your mouse over the term, a popup will appear,
736 describing the meaning of the term.
737 </p>
738
739 <h3>Referencing an already defined Term</h3>
740 <p>
741 Obviously you don't want to define
742 the same term over and over again, just to provide the user the meaning of
743 it at any occurence of the site. That's why our software does that
744 automatically for you once your article is
745 <a href="02_uploading_docs.html">uploaded to our server</a>.
746 Now when you use the term at another place, i.e. in another article, then
747 it will automatically have the same meaning attached to it:
748 </p>
749 <code>
750 <p>
751 Once again he was sitting behind the wheel of his &lt;i&gt;Mega Liner&lt;/i&gt;,
752 but things were different back then.
753 </p>
754 </code>
755 <example>
756 <p>
757 Once again he was sitting behind the wheel of his <i>Mega Liner</i>, but
758 things were different back then.
759 </p>
760 </example>
761 <p>
762 Point your mouse again over the term, and you will notice that the same
763 term definition will popup as tooltip, like at its original location where
764 it was defined before.
765 <p>
766 </p>
767 Due to this fact, our site's software does not even allow you to define the
768 same term more than once (at least not with a different meaning that is).
769 It will scan all documents in our current pool and if somebody tries to
770 re-declare an already existing term again with a different meaning, he
771 will automatically be notified by our system via email and kindly asked
772 to resolve the ambiguousness.
773 </p>
774 <note>
775 Our system automatically handles redundant variants of terms. That means
776 first of all, that all term names are stored, compared and looked up case insensitive,
777 and the system automatically tries to auto complete i.e. plural forms
778 of the same term.
779 </note>
780
781 <h2>Tables</h2>
782 <p>
783 Tables are written like ordinary HTML tables. That is:
784 </p>
785 <code>
786 &lt;table&gt;
787 &lt;tr&gt;
788 &lt;th&gt;Name&lt;/th&gt; &lt;th&gt;Description&lt;/th&gt;
789 &lt;/tr&gt;
790 &lt;tr&gt;
791 &lt;td&gt;Foo&lt;/td&gt; &lt;td&gt;Some text.&lt;/td&gt;
792 &lt;/tr&gt;
793 &lt;tr&gt;
794 &lt;td&gt;Bar&lt;/td&gt; &lt;td&gt;And more text.&lt;/td&gt;
795 &lt;/tr&gt;
796 &lt;tr&gt;
797 &lt;td&gt;Thing&lt;/td&gt; &lt;td&gt;And that's it.&lt;/td&gt;
798 &lt;/tr&gt;
799 &lt;/table&gt;
800 </code>
801 <example>
802 <table>
803 <tr>
804 <th>Name</th> <th>Description</th>
805 </tr>
806 <tr>
807 <td>Foo</td> <td>Some text.</td>
808 </tr>
809 <tr>
810 <td>Bar</td> <td>And more text.</td>
811 </tr>
812 <tr>
813 <td>Thing</td> <td>And that's it.</td>
814 </tr>
815 </table>
816 </example>
817 <p>
818 So <code>&lt;tr&gt;</code> wraps up individual rows of a table,
819 <code>&lt;th&gt;</code> contains the individual cells of the table header,
820 and <code>&lt;td&gt;</code> contains the individual cells of the table's
821 body.
822 </p>
823
824 <h2>Note Boxes</h2>
825 <p>
826 Once in a while you need to inform the reader about noteworthy issues.
827 For this purpose we are using a special <code>&lt;note&gt;</code> tag.
828 </p>
829 <h3>Regular Notes</h3>
830 <p>
831 To add regular notes to your article with low or normal importance, add
832 the note like this:
833 </p>
834 <code>
835 &lt;note&gt;
836 This is an issue you need to know about. Please read this carefully to avoid
837 making any mistakes.
838 &lt;/note&gt;
839 </code>
840 <example>
841 <note>
842 This is an issue you need to know about. Please read this carefully to avoid
843 making any mistakes.
844 </note>
845 </example>
846 <p>
847 This is not a regular HTML tag defined in the HTML standard, but with
848 modern browsers supporting CSS3, it should display just as intended.
849 </p>
850
851 <h3>Important Notes</h3>
852 <p>
853 If you need to inform the reader about a very important issue instead,
854 then you might use the following slightly different form:
855 </p>
856 <code>
857 &lt;note class="important"&gt;
858 Now this is a very important issue you need to be aware of. If you ignore it,
859 your task will fail.
860 &lt;/note&gt;
861 </code>
862 <example>
863 <note class="important">
864 Now this is a very important issue you need to be aware of. If you ignore it,
865 your task will fail.
866 </note>
867 </example>
868 <p>
869 The only thing that changed compared to the regular note, is the "class"
870 attribute of the note tag.
871 </p>
872
873 <h2>Directory Listings</h2>
874 <p>
875 Software components often have a certain kind of directory structure.
876 For readers of your articles is it way easier to perceive directory
877 structures if they are displayed in a visual appropriate way. There are
878 two specials tags you can use for this purpose:
879 </p>
880 <code lang="html">
881 &lt;dir&gt;/
882 &lt;dir&gt;home
883 &lt;dir&gt;bob
884 &lt;file&gt;README.txt&lt;/file&gt;
885 &lt;file&gt;foo.sh&lt;/file&gt;
886 &lt;/dir&gt;
887 &lt;/dir&gt;
888 &lt;dir&gt;tmp
889 &lt;file&gt;bla.tmp&lt;/file&gt;
890 &lt;/dir&gt;
891 &lt;/dir&gt;
892 </code>
893 <example>
894 <dir>/
895 <dir>home
896 <dir>bob
897 <file>README.txt</file>
898 <file>foo.sh</file>
899 </dir>
900 </dir>
901 <dir>tmp
902 <file>bla.tmp</file>
903 </dir>
904 </dir>
905 </example>
906 <p>
907 Currently for each file the same icon will be displayed. This might change
908 in future, i.e. a an automatic different icon could be picked by the
909 site's software according to the respective file name extension.
910 </p>
911
912 <h2>Extensions</h2>
913 <p>
914 This is almost the end of this article. You are still seeking for features
915 for one of your articles, that are not already covered by our system?
916 Then either ask <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>
917 whether that feature could be added, or ... extend your article on your
918 own. It's real HTML after all! So you can add your own HTML, CSS and
919 Java Script to your articles at any time!
920 </p>
921
922 <h2>What next?</h2>
923 <p>
924 You are at the end of our tour introducing our documentation system.
925 You may now start writing your first article. Once you are done with it,
926 simply
927 <a href="http://www.linuxsampler.org/developers.html">send your article to some of us</a>,
928 or request an account to our Subversion repository, so you can
929 manage articles of our documentation site on your own.
930 </p>
931 <p>
932 You already got a Subversion account? Then continue reading
933 <a href="02_uploading_docs.html">how to upload articles</a> for this site.
934 </p>
935 <p>
936 Thanks for your support!
937 </p>
938
939 </body>
940 </html>

  ViewVC Help
Powered by ViewVC