3 |
<meta name="author" content="Christian Schoenebeck"> |
<meta name="author" content="Christian Schoenebeck"> |
4 |
<title>Writing Docs</title> |
<title>Writing Docs</title> |
5 |
<meta name="description" content="Writing new articles for this site."> |
<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> |
</head> |
9 |
<body> |
<body> |
10 |
<p> |
<p> |
124 |
Creating a new article for this site is as simple as creating a new text |
Creating a new article for this site is as simple as creating a new text |
125 |
file and adding following text: |
file and adding following text: |
126 |
</p> |
</p> |
127 |
<code l="html"> |
<code lang="html"> |
128 |
<h1>My First Article</h1> |
<h1>My First Article</h1> |
129 |
<p> |
<p> |
130 |
This is the first paragraph. |
This is the first paragraph. |
291 |
which will be shown at the left side next to your article on our site. |
which will be shown at the left side next to your article on our site. |
292 |
</p> |
</p> |
293 |
<p> |
<p> |
294 |
Once your article is uploaded to our site, IDs for the individual |
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 |
headlines will automatically be generated for you. If for example you had |
297 |
somewhere in your article a headline called "Conclusion of Topic", then |
somewhere in your article a headline called "Conclusion of Topic", then |
298 |
this particular paragraph of your article may be directly linked to from |
this particular paragraph of your article may be directly linked to from |
299 |
other articles or other sites with an URL like |
other articles or other sites with an URL like |
300 |
<code>http://doc.linuxsampler.org/path/to/your/article/#conclusion_of_topic</code>. |
<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 |
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 |
own ID for a paragraph of your article, then simply set the desired ID with |
303 |
your headline: |
your headline: |
304 |
</p> |
</p> |
305 |
<code> |
<code lang="html"> |
306 |
<h3 id="my_conclusion">Conclusion of topic</h3> |
<h3 id="my_conclusion">Conclusion of topic</h3> |
307 |
</code> |
</code> |
308 |
|
|
444 |
|
|
445 |
<h3>Unique Pictures</h3> |
<h3>Unique Pictures</h3> |
446 |
<p> |
<p> |
447 |
Once your article and its picture(s) are uploaded to our server, our |
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 |
system will automatically check that all images on our entire site have |
450 |
unique and unambiguous file names, no matter at which directory they |
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 |
are stored to exactly. The "file name" that is checked in this case, is |
491 |
<code><code></code> tags like this: |
<code><code></code> tags like this: |
492 |
</p> |
</p> |
493 |
<code> |
<code> |
494 |
<code> |
<code lang="??language??"> |
495 |
|
|
496 |
??source-code?? |
??source-code?? |
497 |
|
|
498 |
</code> |
</code> |
499 |
</code> |
</code> |
500 |
<p> |
<p> |
501 |
Syntax highlighting is automatically generated for you, according to the |
Syntax highlighting is automatically generated for you. That way you don't |
|
programming language or markup language used by you. That way you don't |
|
502 |
have to waste time on how to display source code nicely, and rather |
have to waste time on how to display source code nicely, and rather |
503 |
concentrate on the content of your article. Like with images, you can |
concentrate on the content of your article instead. |
504 |
|
You should provide the intended programming language with <code>??language??</code>. |
505 |
|
Obviously it is exhausting to provide such a <code lang="none">lang</code> |
506 |
|
attribute with every single code sample, especially if you are just refering |
507 |
|
a single code token within your paragraphs. So you don't have to do that. |
508 |
|
If you omit the <code lang="none">lang</code> attribute, then our site's |
509 |
|
software will automatically use the language defined by your with one of |
510 |
|
the previous code blocks. |
511 |
|
</p> |
512 |
|
<p> |
513 |
|
Like with images, you can |
514 |
decide in which context the source code shall appear in your article, |
decide in which context the source code shall appear in your article, |
515 |
as described next. |
as described next. |
516 |
</p> |
</p> |
517 |
|
|
518 |
|
<note> |
519 |
|
Automatic syntax highlighting is currently available for the |
520 |
|
<ul> |
521 |
|
<li><a href="nksp.html">NKSP real-time instrument script language</a></li> |
522 |
|
<li>HTML markup language</li> |
523 |
|
</ul> |
524 |
|
If you need another source code language, just tell |
525 |
|
<a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
526 |
|
and he will add the required module for any kind of language |
527 |
|
(even the most exotic one) on our server in short time. |
528 |
|
</note> |
529 |
|
|
530 |
<h3>Stand-Alone Code</h3> |
<h3>Stand-Alone Code</h3> |
531 |
<p> |
<p> |
532 |
If you put your code block outside of paragraphs, that is between |
If you put your code block outside of paragraphs, that is between |
534 |
on its own between the paragraph blocks. Here is an example for the |
on its own between the paragraph blocks. Here is an example for the |
535 |
<a href="nksp.html">NKSP script language</a>. |
<a href="nksp.html">NKSP script language</a>. |
536 |
</p> |
</p> |
537 |
<code> |
<code lang="html"> |
538 |
<p> |
<p> |
539 |
Paragraph just before the source code block. |
Paragraph just before the source code block. |
540 |
</p> |
</p> |
541 |
<code> |
<code lang="nksp"> |
542 |
on init |
on init |
543 |
@foo := "A message" |
@foo := "A message" |
544 |
message(@foo) |
message(@foo) |
580 |
do that: simply put the code block into the paragraph text block of your |
do that: simply put the code block into the paragraph text block of your |
581 |
HTML file: |
HTML file: |
582 |
</p> |
</p> |
583 |
<code> |
<code lang="html"> |
584 |
<p> |
<p> |
585 |
A variable is assigned with NKSP like this <code>$foo := 5</code>, in this |
A variable is assigned with NKSP like this <code>$foo := 5</code>, in this |
586 |
case you are assigning <code>5</code> to the integer variable <code>$foo</code>. |
case you are assigning <code>5</code> to the integer variable <code>$foo</code>. |
601 |
|
|
602 |
<note> |
<note> |
603 |
Syntax highlighting of source code is automatically generated by our site's software |
Syntax highlighting of source code is automatically generated by our site's software |
604 |
once the document is uploaded to our server. So when you are just |
once the document is |
605 |
|
<a href="02_uploading_docs.html">uploaded to our server</a>. |
606 |
|
So when you are just |
607 |
previewing your article with source code snippets on your local machine, |
previewing your article with source code snippets on your local machine, |
608 |
then those source code snippets will yet be displayed monochrome, |
then those source code snippets will yet be displayed monochrome, |
609 |
without any syntax highlighting. |
without any syntax highlighting. |
610 |
</note> |
</note> |
611 |
|
|
|
<note> |
|
|
Automatic syntax highlighting is currently available for the |
|
|
<ul> |
|
|
<li>NKSP real-time instrument script language |
|
|
<li>HTML markup language</li> |
|
|
</ul> |
|
|
If you need another source code language, just tell |
|
|
<a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
|
|
and he will add the required module for any kind of language |
|
|
(even the most exotic one) on our server in short time. |
|
|
</note> |
|
|
|
|
612 |
<h3>Metaphors</h3> |
<h3>Metaphors</h3> |
613 |
<p> |
<p> |
614 |
You might have noticed, we have used a special kind of <code>??place-holder??</code> for |
You might have noticed, we have used a special kind of <code lang="html">??place-holder??</code> for |
615 |
human-readable portions in source code before, which shall outline to the reader |
human-readable portions in source code before, which shall outline to the reader |
616 |
that it is not actually "real" source code, but just reflecting its semantic meaning. |
that it is not actually "real" source code, but just reflecting its semantic meaning. |
617 |
Simply put the respective pseudo-code into a pair of two question marks, |
Simply put the respective pseudo-code into a pair of two question marks, |
618 |
like so: |
like so: |
619 |
</p> |
</p> |
620 |
<code> |
<code lang="html"> |
621 |
<code> |
<code> |
622 |
on init |
on init |
623 |
declare const $i = \?\?some-value\?\? |
declare const $i = \?\?some-value\?\? |
650 |
If you want to add links in your article to another article or to some |
If you want to add links in your article to another article or to some |
651 |
other website, then you just use an ordinary HTML link tag pair: |
other website, then you just use an ordinary HTML link tag pair: |
652 |
</p> |
</p> |
653 |
<code> |
<code lang="html"> |
654 |
<p> |
<p> |
655 |
This paragraph contains <a href="../nksp.html">a link to another article</a> |
This paragraph contains <a href="../nksp.html">a link to another article</a> |
656 |
and to <a href="http://www.linuxsampler.org">another website</a>. |
and to <a href="http://www.linuxsampler.org">another website</a>. |
680 |
An article file on our site usually has the following |
An article file on our site usually has the following |
681 |
file name form: |
file name form: |
682 |
</p> |
</p> |
683 |
<code> |
<code lang="none"> |
684 |
??number-prefix??_??unique-name??.html |
??number-prefix??_??unique-name??.html |
685 |
</code> |
</code> |
686 |
<p> |
<p> |
703 |
Technical terms and abbreviations are often used in articles to reduce |
Technical terms and abbreviations are often used in articles to reduce |
704 |
the amount of text for transmitting some kind of information about a |
the amount of text for transmitting some kind of information about a |
705 |
certain topic to the reader. You might want to emphasize technical terms and abbreviations |
certain topic to the reader. You might want to emphasize technical terms and abbreviations |
706 |
in your article, by wrapping the term into a pair of <code><i></code> HTML |
in your article, by wrapping the term into a pair of <code lang="html"><i></code> HTML |
707 |
tags. On our site this will not only show the term in a special unified |
tags. On our site this will not only show the term in a special unified |
708 |
font style (currently italic), but it allows you also to define the |
font style (currently italic), but it allows you also to define the |
709 |
meaning of the term <b>once</b>. Which goes like this: |
meaning of the term <b>once</b>. Which goes like this: |
713 |
<p> |
<p> |
714 |
You may define a new term like this: |
You may define a new term like this: |
715 |
</p> |
</p> |
716 |
<code> |
<code lang="html"> |
717 |
<p> |
<p> |
718 |
He left the bar and jumped right into his |
He left the bar and jumped right into his |
719 |
<i title="A very large vehicle.">Mega Liner</i> |
<i title="A very large vehicle.">Mega Liner</i> |
737 |
Obviously you don't want to define |
Obviously you don't want to define |
738 |
the same term over and over again, just to provide the user the meaning of |
the same term over and over again, just to provide the user the meaning of |
739 |
it at any occurence of the site. That's why our software does that |
it at any occurence of the site. That's why our software does that |
740 |
automatically for you once your article is uploaded to our server. Now |
automatically for you once your article is |
741 |
when you use the term at another place, i.e. in another article, then |
<a href="02_uploading_docs.html">uploaded to our server</a>. |
742 |
|
Now when you use the term at another place, i.e. in another article, then |
743 |
it will automatically have the same meaning attached to it: |
it will automatically have the same meaning attached to it: |
744 |
</p> |
</p> |
745 |
<code> |
<code> |
779 |
Tables are written like ordinary HTML tables. That is: |
Tables are written like ordinary HTML tables. That is: |
780 |
</p> |
</p> |
781 |
<code> |
<code> |
782 |
<table> |
<table> |
783 |
<tr> |
<tr> |
784 |
<th>Name</th> <th>Description</th> |
<th>Name</th> <th>Description</th> |
785 |
</tr> |
</tr> |
786 |
<tr> |
<tr> |
787 |
<td>Foo</td> <td>Some text.</td> |
<td>Foo</td> <td>Some text.</td> |
788 |
</tr> |
</tr> |
789 |
<tr> |
<tr> |
790 |
<td>Bar</td> <td>And more text.</td> |
<td>Bar</td> <td>And more text.</td> |
791 |
</tr> |
</tr> |
792 |
<tr> |
<tr> |
793 |
<td>Thing</td> <td>And that's it.</td> |
<td>Thing</td> <td>And that's it.</td> |
794 |
</tr> |
</tr> |
795 |
</table> |
</table> |
796 |
</code> |
</code> |
797 |
<example> |
<example> |
798 |
<table> |
<table> |
881 |
You are at the end of our tour introducing our documentation system. |
You are at the end of our tour introducing our documentation system. |
882 |
You may now start writing your first article. Once you are done with it, |
You may now start writing your first article. Once you are done with it, |
883 |
simply |
simply |
884 |
<a href="http://www.linuxsampler.org/developers.html"> |
<a href="http://www.linuxsampler.org/developers.html">send your article to some of us</a>, |
885 |
send your article to some of us |
or request an account to our Subversion repository, so you can |
|
</a>, or request an account to our Subversion repository, so you can |
|
886 |
manage articles of our documentation site on your own. |
manage articles of our documentation site on your own. |
887 |
</p> |
</p> |
888 |
<p> |
<p> |
889 |
|
You already got a Subversion account? Then continue reading |
890 |
|
<a href="02_uploading_docs.html">how to upload articles</a> for this site. |
891 |
|
</p> |
892 |
|
<p> |
893 |
Thanks for your support! |
Thanks for your support! |
894 |
</p> |
</p> |
895 |
|
|