@@ -122,7 +124,7 @@ Creating a new article for this site is as simple as creating a new text file and adding following text:
-
+
My First Article
This is the first paragraph.
@@ -289,17 +291,18 @@
which will be shown at the left side next to your article on our site.
- Once your article is uploaded to our site, IDs for the individual
+ Once your article is
+ uploaded to our site, IDs for the individual
headlines will automatically be generated for you. If for example you had
somewhere in your article a headline called "Conclusion of Topic", then
this particular paragraph of your article may be directly linked to from
other articles or other sites with an URL like
- http://doc.linuxsampler.org/path/to/your/article/#conclusion_of_topic.
+ http://doc.linuxsampler.org/path/to/your/article/#conclusion_of_topic.
If you want to override this behavior, because you rather want to use your
own ID for a paragraph of your article, then simply set the desired ID with
your headline:
-
+
Conclusion of topic
@@ -441,7 +444,8 @@
Unique Pictures
- Once your article and its picture(s) are uploaded to our server, our
+ Once your article and its picture(s) are
+ uploaded to our server, our
system will automatically check that all images on our entire site have
unique and unambiguous file names, no matter at which directory they
are stored to exactly. The "file name" that is checked in this case, is
@@ -487,17 +491,29 @@
<code> tags like this:
-<code>
+<code lang="??language??">
??source-code??
</code>
- Syntax highlighting is automatically generated for you, according to the
- programming language or markup language used by you. That way you don't
+ Syntax highlighting is automatically generated for you. That way you don't
have to waste time on how to display source code nicely, and rather
- concentrate on the content of your article. Like with images, you can
+ concentrate on the content of your article instead.
+ You should provide the intended programming language of your source code sample
+ with ??language??.
+ Obviously it is exhausting to supply such a lang
+ attribute with every single code sample, especially if you are just referring
+ to a single code token within your paragraphs. So you don't have to do that.
+ If you omit the lang attribute, then our site's
+ software will automatically use the language defined by you with one of
+ the previous code blocks. You may also disable automatic syntax highlighting
+ with <code lang="none">, which will cause
+ that code block to appear simply in monochrome color.
+
+
+ Like with images, you can
decide in which context the source code shall appear in your article,
as described next.
@@ -521,11 +537,11 @@
on its own between the paragraph blocks. Here is an example for the
NKSP script language.
-
+
Paragraph just before the source code block.
-<code>
+<code lang="nksp">
on init
@foo := "A message"
message(@foo)
@@ -567,7 +583,7 @@
do that: simply put the code block into the paragraph text block of your
HTML file:
-
+
A variable is assigned with NKSP like this <code>$foo := 5</code>, in this
case you are assigning <code>5</code> to the integer variable <code>$foo</code>.
@@ -588,7 +604,9 @@
Syntax highlighting of source code is automatically generated by our site's software
- once the document is uploaded to our server. So when you are just
+ once the document is
+ uploaded to our server.
+ So when you are just
previewing your article with source code snippets on your local machine,
then those source code snippets will yet be displayed monochrome,
without any syntax highlighting.
@@ -596,13 +614,13 @@
Metaphors
- You might have noticed, we have used a special kind of ??place-holder?? for
+ You might have noticed, we have used a special kind of ??place-holder?? for
human-readable portions in source code before, which shall outline to the reader
that it is not actually "real" source code, but just reflecting its semantic meaning.
Simply put the respective pseudo-code into a pair of two question marks,
like so:
-
+
<code>
on init
declare const $i = \?\?some-value\?\?
@@ -635,7 +653,7 @@
If you want to add links in your article to another article or to some
other website, then you just use an ordinary HTML link tag pair:
-
+
This paragraph contains <a href="../nksp.html">a link to another article</a>
and to <a href="http://www.linuxsampler.org">another website</a>.
@@ -665,7 +683,7 @@
An article file on our site usually has the following
file name form:
-
+
??number-prefix??_??unique-name??.html
@@ -688,7 +706,7 @@
Technical terms and abbreviations are often used in articles to reduce
the amount of text for transmitting some kind of information about a
certain topic to the reader. You might want to emphasize technical terms and abbreviations
- in your article, by wrapping the term into a pair of
You may define a new term like this:
-
+
He left the bar and jumped right into his
<i title="A very large vehicle.">Mega Liner</i>
@@ -722,8 +740,9 @@
Obviously you don't want to define
the same term over and over again, just to provide the user the meaning of
it at any occurence of the site. That's why our software does that
- automatically for you once your article is uploaded to our server. Now
- when you use the term at another place, i.e. in another article, then
+ automatically for you once your article is
+ uploaded to our server.
+ Now when you use the term at another place, i.e. in another article, then
it will automatically have the same meaning attached to it:
@@ -849,7 +868,46 @@
The only thing that changed compared to the regular note, is the "class"
attribute of the note tag.
-
+
+ Directory Listings
+
+ Software components often have a certain kind of directory structure.
+ For readers of your articles is it way easier to perceive directory
+ structures if they are displayed in a visual appropriate way. There are
+ two specials tags you can use for this purpose:
+
+
+ <dir>/
+ <dir>home
+ <dir>bob
+ <file>README.txt</file>
+ <file>foo.sh</file>
+ </dir>
+ </dir>
+ <dir>tmp
+ <file>bla.tmp</file>
+ </dir>
+ </dir>
+
+
+ /
+ home
+ bob
+ README.txt
+ foo.sh
+
+
+ tmp
+ bla.tmp
+
+
+
+
+ Currently for each file the same icon will be displayed. This might change
+ in future, i.e. a an automatic different icon could be picked by the
+ site's software according to the respective file name extension.
+
+
Extensions
This is almost the end of this article. You are still seeking for features
@@ -865,12 +923,15 @@
You are at the end of our tour introducing our documentation system.
You may now start writing your first article. Once you are done with it,
simply
-
- send your article to some of us
- , or request an account to our Subversion repository, so you can
+ send your article to some of us,
+ or request an account to our Subversion repository, so you can
manage articles of our documentation site on your own.
+ You already got a Subversion account? Then continue reading
+ how to upload articles for this site.
+
+
Thanks for your support!