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 |
|
|
387 |
</p> |
</p> |
388 |
</example> |
</example> |
389 |
<p> |
<p> |
390 |
You also don't have to care about the size of the image. If the image |
You also don't have to worry about the size of the image. If the image |
391 |
resolution is largen than the width of the article would currently require |
resolution is larger than the width of the article would currently require |
392 |
on the user's screen, then the image will automatically be downscaled to |
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 |
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 |
of images approximately below 1200px, just to not waste too much repository space |
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 of your source code sample |
505 |
|
with <code>??language??</code>. |
506 |
|
Obviously it is exhausting to supply such a <code lang="none">lang</code> |
507 |
|
attribute with every single code sample, especially if you are just referring |
508 |
|
to a single code token within your paragraphs. So you don't have to do that. |
509 |
|
If you omit the <code lang="none">lang</code> attribute, then our site's |
510 |
|
software will automatically use the language defined by you with one of |
511 |
|
the previous code blocks. You may also disable automatic syntax highlighting |
512 |
|
with <code lang="html"><code lang="none"></code>, which will cause |
513 |
|
that code block to appear simply in monochrome color. |
514 |
|
</p> |
515 |
|
<p> |
516 |
|
Like with images, you can |
517 |
decide in which context the source code shall appear in your article, |
decide in which context the source code shall appear in your article, |
518 |
as described next. |
as described next. |
519 |
</p> |
</p> |
520 |
|
|
521 |
|
<note> |
522 |
|
Automatic syntax highlighting is currently available for the |
523 |
|
<ul> |
524 |
|
<li><a href="nksp.html">NKSP real-time instrument script language</a></li> |
525 |
|
<li>HTML markup language</li> |
526 |
|
</ul> |
527 |
|
If you need another source code language, just tell |
528 |
|
<a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a> |
529 |
|
and he will add the required module for any kind of language |
530 |
|
(even the most exotic one) on our server in short time. |
531 |
|
</note> |
532 |
|
|
533 |
<h3>Stand-Alone Code</h3> |
<h3>Stand-Alone Code</h3> |
534 |
<p> |
<p> |
535 |
If you put your code block outside of paragraphs, that is between |
If you put your code block outside of paragraphs, that is between |
537 |
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 |
538 |
<a href="nksp.html">NKSP script language</a>. |
<a href="nksp.html">NKSP script language</a>. |
539 |
</p> |
</p> |
540 |
<code> |
<code lang="html"> |
541 |
<p> |
<p> |
542 |
Paragraph just before the source code block. |
Paragraph just before the source code block. |
543 |
</p> |
</p> |
544 |
<code> |
<code lang="nksp"> |
545 |
on init |
on init |
546 |
@foo := "A message" |
@foo := "A message" |
547 |
message(@foo) |
message(@foo) |
583 |
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 |
584 |
HTML file: |
HTML file: |
585 |
</p> |
</p> |
586 |
<code> |
<code lang="html"> |
587 |
<p> |
<p> |
588 |
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 |
589 |
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>. |
604 |
|
|
605 |
<note> |
<note> |
606 |
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 |
607 |
once the document is uploaded to our server. So when you are just |
once the document is |
608 |
|
<a href="02_uploading_docs.html">uploaded to our server</a>. |
609 |
|
So when you are just |
610 |
previewing your article with source code snippets on your local machine, |
previewing your article with source code snippets on your local machine, |
611 |
then those source code snippets will yet be displayed monochrome, |
then those source code snippets will yet be displayed monochrome, |
612 |
without any syntax highlighting. |
without any syntax highlighting. |
613 |
</note> |
</note> |
614 |
|
|
|
<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> |
|
|
|
|
615 |
<h3>Metaphors</h3> |
<h3>Metaphors</h3> |
616 |
<p> |
<p> |
617 |
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 |
618 |
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 |
619 |
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. |
620 |
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, |
621 |
like so: |
like so: |
622 |
</p> |
</p> |
623 |
<code> |
<code lang="html"> |
624 |
<code> |
<code> |
625 |
on init |
on init |
626 |
declare const $i = \?\?some-value\?\? |
declare const $i = \?\?some-value\?\? |
653 |
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 |
654 |
other website, then you just use an ordinary HTML link tag pair: |
other website, then you just use an ordinary HTML link tag pair: |
655 |
</p> |
</p> |
656 |
<code> |
<code lang="html"> |
657 |
<p> |
<p> |
658 |
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> |
659 |
and to <a href="http://www.linuxsampler.org">another website</a>. |
and to <a href="http://www.linuxsampler.org">another website</a>. |
683 |
An article file on our site usually has the following |
An article file on our site usually has the following |
684 |
file name form: |
file name form: |
685 |
</p> |
</p> |
686 |
<code> |
<code lang="none"> |
687 |
??number-prefix??_??unique-name??.html |
??number-prefix??_??unique-name??.html |
688 |
</code> |
</code> |
689 |
<p> |
<p> |
706 |
Technical terms and abbreviations are often used in articles to reduce |
Technical terms and abbreviations are often used in articles to reduce |
707 |
the amount of text for transmitting some kind of information about a |
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 |
certain topic to the reader. You might want to emphasize technical terms and abbreviations |
709 |
in your article, by wrapping the term into a pair of <code><i></code> HTML |
in your article, by wrapping the term into a pair of <code lang="html"><i></code> HTML |
710 |
tags. On our site this will not only show the term in a special unified |
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 |
font style (currently italic), but it allows you also to define the |
712 |
meaning of the term <b>once</b>. Which goes like this: |
meaning of the term <b>once</b>. Which goes like this: |
716 |
<p> |
<p> |
717 |
You may define a new term like this: |
You may define a new term like this: |
718 |
</p> |
</p> |
719 |
<code> |
<code lang="html"> |
720 |
<p> |
<p> |
721 |
He left the bar and jumped right into his |
He left the bar and jumped right into his |
722 |
<i title="A very large vehicle.">Mega Liner</i> |
<i title="A very large vehicle.">Mega Liner</i> |
740 |
Obviously you don't want to define |
Obviously you don't want to define |
741 |
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 |
742 |
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 |
743 |
automatically for you once your article is uploaded to our server. Now |
automatically for you once your article is |
744 |
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>. |
745 |
|
Now when you use the term at another place, i.e. in another article, then |
746 |
it will automatically have the same meaning attached to it: |
it will automatically have the same meaning attached to it: |
747 |
</p> |
</p> |
748 |
<code> |
<code> |
782 |
Tables are written like ordinary HTML tables. That is: |
Tables are written like ordinary HTML tables. That is: |
783 |
</p> |
</p> |
784 |
<code> |
<code> |
785 |
<table> |
<table> |
786 |
<tr> |
<tr> |
787 |
<th>Name</th> <th>Description</th> |
<th>Name</th> <th>Description</th> |
788 |
</tr> |
</tr> |
789 |
<tr> |
<tr> |
790 |
<td>Foo</td> <td>Some text.</td> |
<td>Foo</td> <td>Some text.</td> |
791 |
</tr> |
</tr> |
792 |
<tr> |
<tr> |
793 |
<td>Bar</td> <td>And more text.</td> |
<td>Bar</td> <td>And more text.</td> |
794 |
</tr> |
</tr> |
795 |
<tr> |
<tr> |
796 |
<td>Thing</td> <td>And that's it.</td> |
<td>Thing</td> <td>And that's it.</td> |
797 |
</tr> |
</tr> |
798 |
</table> |
</table> |
799 |
</code> |
</code> |
800 |
<example> |
<example> |
801 |
<table> |
<table> |
868 |
The only thing that changed compared to the regular note, is the "class" |
The only thing that changed compared to the regular note, is the "class" |
869 |
attribute of the note tag. |
attribute of the note tag. |
870 |
</p> |
</p> |
871 |
|
|
872 |
|
<h2>Directory Listings</h2> |
873 |
|
<p> |
874 |
|
Software components often have a certain kind of directory structure. |
875 |
|
For readers of your articles is it way easier to perceive directory |
876 |
|
structures if they are displayed in a visual appropriate way. There are |
877 |
|
two specials tags you can use for this purpose: |
878 |
|
</p> |
879 |
|
<code lang="html"> |
880 |
|
<dir>/ |
881 |
|
<dir>home |
882 |
|
<dir>bob |
883 |
|
<file>README.txt</file> |
884 |
|
<file>foo.sh</file> |
885 |
|
</dir> |
886 |
|
</dir> |
887 |
|
<dir>tmp |
888 |
|
<file>bla.tmp</file> |
889 |
|
</dir> |
890 |
|
</dir> |
891 |
|
</code> |
892 |
|
<example> |
893 |
|
<dir>/ |
894 |
|
<dir>home |
895 |
|
<dir>bob |
896 |
|
<file>README.txt</file> |
897 |
|
<file>foo.sh</file> |
898 |
|
</dir> |
899 |
|
</dir> |
900 |
|
<dir>tmp |
901 |
|
<file>bla.tmp</file> |
902 |
|
</dir> |
903 |
|
</dir> |
904 |
|
</example> |
905 |
|
<p> |
906 |
|
Currently for each file the same icon will be displayed. This might change |
907 |
|
in future, i.e. a an automatic different icon could be picked by the |
908 |
|
site's software according to the respective file name extension. |
909 |
|
</p> |
910 |
|
|
911 |
<h2>Extensions</h2> |
<h2>Extensions</h2> |
912 |
<p> |
<p> |
913 |
This is almost the end of this article. You are still seeking for features |
This is almost the end of this article. You are still seeking for features |
923 |
You are at the end of our tour introducing our documentation system. |
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, |
You may now start writing your first article. Once you are done with it, |
925 |
simply |
simply |
926 |
<a href="http://www.linuxsampler.org/developers.html"> |
<a href="http://www.linuxsampler.org/developers.html">send your article to some of us</a>, |
927 |
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 |
|
928 |
manage articles of our documentation site on your own. |
manage articles of our documentation site on your own. |
929 |
</p> |
</p> |
930 |
<p> |
<p> |
931 |
|
You already got a Subversion account? Then continue reading |
932 |
|
<a href="02_uploading_docs.html">how to upload articles</a> for this site. |
933 |
|
</p> |
934 |
|
<p> |
935 |
Thanks for your support! |
Thanks for your support! |
936 |
</p> |
</p> |
937 |
|
|