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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2732 - (hide annotations) (download) (as text)
Sun Apr 26 20:54:00 2015 UTC (6 years, 2 months ago) by schoenebeck
File MIME type: text/html
File size: 36271 byte(s)
* Initial import of doc.linuxsampler.org.

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

  ViewVC Help
Powered by ViewVC