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

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

Parent Directory | Revision Log | View Patch Patch

-revision 2739 by schoenebeck,
Tue Apr 28 19:33:56 2015 UTC
+revision 3083 by schoenebeck,
Mon Jan  9 19:23:58 2017 UTC
 Line 124
        Creating a new article for this site is as simple as creating a new text
        file and adding following text:
      </p>
-     <code l="html">
+     <code lang="html">
  <h1>My First Article</h1>
  <p>
    This is the first paragraph.
 Line 297
        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
-       <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>.
        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:
      </p>
-     <code>
+     <code lang="html">
  <h3 id="my_conclusion">Conclusion of topic</h3>
      </code>
 Line 365
    This is the first paragraph. Just before the picture.
  </p>
- <img src="some_picture.png" caption="??footnote??" title="??tooltip-text??">
+ &lt;img src="some_picture.png" caption="??footnote??" title="??tooltip-text??"&gt;
  <p>
    This is the next paragraph, just after the picture.
 Line 387
        </p>
      </example>
      <p>
-       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
-       resolution is largen than the width of the article would currently require
+       resolution is larger than the width of the article would currently require
        on the user's screen, then the image will automatically be downscaled to
        fit the width of the article. It is recommended though to keep the width
        of images approximately below 1200px, just to not waste too much repository space
 Line 491
        <code>&lt;code&gt;</code> tags like this:
      </p>
      <code>
- &lt;code&gt;
+ &lt;code lang="??language??"&gt;
    ??source-code??
  &lt;/code&gt;
      </code>
      <p>
-       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
        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 <code>??language??</code>.
+       Obviously it is exhausting to supply such a <code lang="none">lang</code>
+       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 <code lang="none">lang</code> 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="html">&lt;code lang="none"&gt;</code>, which will cause
+       that code block to appear simply in monochrome color.
+     </p>
+     <p>
+       Like with images, you can
        decide in which context the source code shall appear in your article,
        as described next.
      </p>
-Line 511
+Line 523
        <ul>
          <li><a href="nksp.html">NKSP real-time instrument script language</a></li>
          <li>HTML markup language</li>
+         <li><a href="sfz.html">SFZ File Format</a></li>
        </ul>
        If you need another source code language, just tell
        <a href="http://www.linuxsampler.org/developers.html#Schoenebeck">Christian</a>
-Line 525
+Line 538
        on its own between the paragraph blocks. Here is an example for the
        <a href="nksp.html">NKSP script language</a>.
      </p>
-     <code>
+     <code lang="html">
  <p>
    Paragraph just before the source code block.
  </p>
- &lt;code&gt;
+ &lt;code lang="nksp"&gt;
  on init
    @foo := "A message"
    message(@foo)
-Line 571 
 end on
+Line 584 
 end on
        do that: simply put the code block into the paragraph text block of your
        HTML file:
      </p>
-     <code>
+     <code lang="html">
  <p>
    A variable is assigned with NKSP like this &lt;code&gt;$foo := 5&lt;/code&gt;, in this
    case you are assigning &lt;code&gt;5&lt;/code&gt; to the integer variable &lt;code&gt;$foo&lt;/code&gt;.
-Line 602 
 end on
+Line 615 
 end on
      <h3>Metaphors</h3>
      <p>
-       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
        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:
      </p>
-     <code>
+     <code lang="html">
  &lt;code&gt;
  on init
    declare const $i = \?\?some-value\?\?
-Line 641 
 end on
+Line 654 
 end on
        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:
      </p>
-     <code>
+     <code lang="html">
  <p>
    This paragraph contains &lt;a href="../nksp.html"&gt;a link to another article&lt;/a&gt;
    and to &lt;a href="http://www.linuxsampler.org"&gt;another website&lt;/a&gt;.
-Line 671 
 end on
+Line 684 
 end on
        An article file on our site usually has the following
        file name form:
      </p>
-     <code>
+     <code lang="none">
  ??number-prefix??_??unique-name??.html
      </code>
      <p>
-Line 694 
 end on
+Line 707 
 end on
        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 <code><i></code> HTML
+       in your article, by wrapping the term into a pair of <code lang="html"><i></code> HTML
        tags. On our site this will not only show the term in a special unified
        font style (currently italic), but it allows you also to define the
        meaning of the term <b>once</b>. Which goes like this:
-Line 704 
 end on
+Line 717 
 end on
       <p>
        You may define a new term like this:
      </p>
-     <code>
+     <code lang="html">
  <p>
    He left the bar and jumped right into his
    &lt;i title="A very large vehicle."&gt;Mega Liner&lt;/i&gt;
-Line 856 
 end on
+Line 869 
 end on
        The only thing that changed compared to the regular note, is the "class"
        attribute of the note tag.
      </p>
+     <h2>Directory Listings</h2>
+     <p>
+       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:
+     </p>
+     <code lang="html">
+ &lt;dir&gt;/
+   &lt;dir&gt;home
+     &lt;dir&gt;bob
+       &lt;file&gt;README.txt&lt;/file&gt;
+       &lt;file&gt;foo.sh&lt;/file&gt;
+     &lt;/dir&gt;
+   &lt;/dir&gt;
+   &lt;dir&gt;tmp
+     &lt;file&gt;bla.tmp&lt;/file&gt;
+   &lt;/dir&gt;
+ &lt;/dir&gt;
+     </code>
+     <example>
+       <dir>/
+         <dir>home
+           <dir>bob
+             <file>README.txt</file>
+             <file>foo.sh</file>
+           </dir>
+         </dir>
+         <dir>tmp
+           <file>bla.tmp</file>
+         </dir>
+       </dir>
+     </example>
+     <p>
+       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.
+     </p>
      <h2>Extensions</h2>
      <p>
        This is almost the end of this article. You are still seeking for features
-Line 872 
 end on
+Line 924 
 end on
        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
-       <a href="http://www.linuxsampler.org/developers.html">
+       <a href="http://www.linuxsampler.org/developers.html">send your article to some of us</a>,
-         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
        manage articles of our documentation site on your own.
      </p>
      <p>

 Legend:



Removed from v.2739
 


changed lines


 
Added in v.3083
 Legend:



Removed from v.2739
 


changed lines


 
Added in v.3083
-Removed from v.2739
+Added in v.3083

	ViewVC Help
Powered by ViewVC