/[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 2748 - (hide annotations) (download) (as text)
Wed Apr 29 10:55:48 2015 UTC (8 years, 11 months ago) by schoenebeck
File MIME type: text/html
File size: 38990 byte(s)
* Article "Writing Docs":
  - New chapter "Directory Listings" added.

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 schoenebeck 2738 <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 schoenebeck 2732 </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 schoenebeck 2741 <code lang="html">
128 schoenebeck 2732 <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 schoenebeck 2739 Once your article is
295     <a href="02_uploading_docs.html">uploaded to our site</a>, IDs for the individual
296 schoenebeck 2732 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 schoenebeck 2741 <code lang="none">http://doc.linuxsampler.org/path/to/your/article/#conclusion_of_topic</code>.
301 schoenebeck 2732 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 schoenebeck 2741 <code lang="html">
306 schoenebeck 2732 <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 care about the size of the image. If the image
391     resolution is largen 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 schoenebeck 2739 Once your article and its picture(s) are
448     <a href="02_uploading_docs.html">uploaded to our server</a>, our
449 schoenebeck 2732 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 schoenebeck 2743 &lt;code lang="??language??"&gt;
495 schoenebeck 2732
496     ??source-code??
497    
498     &lt;/code&gt;
499     </code>
500     <p>
501 schoenebeck 2744 Syntax highlighting is automatically generated for you. That way you don't
502 schoenebeck 2732 have to waste time on how to display source code nicely, and rather
503 schoenebeck 2744 concentrate on the content of your article instead.
504 schoenebeck 2747 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 schoenebeck 2748 to a single code token within your paragraphs. So you don't have to do that.
509 schoenebeck 2743 If you omit the <code lang="none">lang</code> attribute, then our site's
510 schoenebeck 2747 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 schoenebeck 2743 </p>
515     <p>
516     Like with images, you can
517 schoenebeck 2732 decide in which context the source code shall appear in your article,
518     as described next.
519     </p>
520    
521 schoenebeck 2733 <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 schoenebeck 2732 <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 schoenebeck 2743 <code lang="html">
541 schoenebeck 2732 <p>
542     Paragraph just before the source code block.
543     </p>
544 schoenebeck 2743 &lt;code lang="nksp"&gt;
545 schoenebeck 2732 on init
546     @foo := "A message"
547     message(@foo)
548     end on
549     &lt;/code&gt;
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 schoenebeck 2741 <code lang="html">
587 schoenebeck 2732 <p>
588     A variable is assigned with NKSP like this &lt;code&gt;$foo := 5&lt;/code&gt;, in this
589     case you are assigning &lt;code&gt;5&lt;/code&gt; to the integer variable &lt;code&gt;$foo&lt;/code&gt;.
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 schoenebeck 2739 once the document is
608     <a href="02_uploading_docs.html">uploaded to our server</a>.
609     So when you are just
610 schoenebeck 2732 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 schoenebeck 2741 You might have noticed, we have used a special kind of <code lang="html">??place-holder??</code> for
618 schoenebeck 2732 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 schoenebeck 2741 <code lang="html">
624 schoenebeck 2732 &lt;code&gt;
625     on init
626     declare const $i = \?\?some-value\?\?
627    
628     message(\?\?text-string\?\?)
629     end on
630     &lt;/code&gt;
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 schoenebeck 2741 <code lang="html">
657 schoenebeck 2732 <p>
658     This paragraph contains &lt;a href="../nksp.html"&gt;a link to another article&lt;/a&gt;
659     and to &lt;a href="http://www.linuxsampler.org"&gt;another website&lt;/a&gt;.
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 schoenebeck 2741 <code lang="none">
687 schoenebeck 2732 ??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 schoenebeck 2741 in your article, by wrapping the term into a pair of <code lang="html"><i></code> HTML
710 schoenebeck 2732 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 schoenebeck 2741 <code lang="html">
720 schoenebeck 2732 <p>
721     He left the bar and jumped right into his
722     &lt;i title="A very large vehicle."&gt;Mega Liner&lt;/i&gt;
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 schoenebeck 2739 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 schoenebeck 2732 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 &lt;i&gt;Mega Liner&lt;/i&gt;,
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 schoenebeck 2735 &lt;table&gt;
786     &lt;tr&gt;
787     &lt;th&gt;Name&lt;/th&gt; &lt;th&gt;Description&lt;/th&gt;
788     &lt;/tr&gt;
789     &lt;tr&gt;
790     &lt;td&gt;Foo&lt;/td&gt; &lt;td&gt;Some text.&lt;/td&gt;
791     &lt;/tr&gt;
792     &lt;tr&gt;
793     &lt;td&gt;Bar&lt;/td&gt; &lt;td&gt;And more text.&lt;/td&gt;
794     &lt;/tr&gt;
795     &lt;tr&gt;
796     &lt;td&gt;Thing&lt;/td&gt; &lt;td&gt;And that's it.&lt;/td&gt;
797     &lt;/tr&gt;
798     &lt;/table&gt;
799 schoenebeck 2732 </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>&lt;tr&gt;</code> wraps up individual rows of a table,
818     <code>&lt;th&gt;</code> contains the individual cells of the table header,
819     and <code>&lt;td&gt;</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>&lt;note&gt;</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     &lt;note&gt;
835     This is an issue you need to know about. Please read this carefully to avoid
836     making any mistakes.
837     &lt;/note&gt;
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     &lt;note class="important"&gt;
857     Now this is a very important issue you need to be aware of. If you ignore it,
858     your task will fail.
859     &lt;/note&gt;
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 schoenebeck 2748
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     &lt;dir&gt;/
881     &lt;dir&gt;home
882     &lt;dir&gt;bob
883     &lt;file&gt;README.txt&lt;/file&gt;
884     &lt;file&gt;foo.sh&lt;/file&gt;
885     &lt;/dir&gt;
886     &lt;/dir&gt;
887     &lt;dir&gt;tmp
888     &lt;file&gt;bla.tmp&lt;/file&gt;
889     &lt;/dir&gt;
890     &lt;/dir&gt;
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 schoenebeck 2732 <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 schoenebeck 2746 <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 schoenebeck 2732 manage articles of our documentation site on your own.
929     </p>
930     <p>
931 schoenebeck 2739 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 schoenebeck 2732 Thanks for your support!
936     </p>
937    
938     </body>
939     </html>

  ViewVC Help
Powered by ViewVC