Picolisp Wiki Quickstart

Table of contents

1. How to contribute?
2. Markup summary
3. Markup description
4. Picolisp Wiki mode for Emacs

How to contribute?

How to contribute to the PicoLisp Wiki? First, you need an account. Click on the Log in link, then press the Create account button on the next page and fill out the form.

Once you are logged in with you new account, go to the wiki section where you want to add something, e.g. the Articles & Essays page. Click on the edit link on top of the page.

Add a new internal link to the page that points to your (still non-existing) new article:

={myarticle This is a short description of my article}

Add a Summary for your change, have a look at the Preview, and when the new link looks fine, save the page.

Refresh the edited page and click on the new link. You will be offered to create the new (but still non-existing) page the link points to, i.e. you will be offered a form for your new page myarticle.

Write your article inside the form, using the syntax described above, don't forget to add a little Summary message like "Added my first article", have a look at the Preview again, and then save it.

Now your new article should exist in the wiki, and it should be accessible from the Articles & Essays page.

Markup summary

The Wiki Markup has a very simple syntax. It always starts with a single character (that specifies the type of markup) followed by an opening brace, and extends till the matching closing brace.

Currently, the following markup types are supported:

Structural markup

• Headings n{Heading} (n between 1 and 6) → <hn>Heading</hn>
• Unordered list *{(unordered list items)} → <ul>(unordered list items)</ul>
• Ordered list +{(ordered list items)} → <ol>(ordered list items)</ol>
• List item -{list item} → <li>list item</li>
• Table %{table contents} → <table>table contents</table>
• Table row ~{row content} → <tr>row content</tr>
• Table cell |{cell content} → <td>cell content</td>
• Preformated text

  :{
  preformated text}

  → <pre>
  preformated text</pre>
• Line break &{n} (n is a natural number) → as many <br/> as n
• Line break with cleared floating elements &{-n} (n is a natural number) → as above, but the first is <br class="clr"/>

Appearance markup

• Italics /{Italics} → <i>Italics</i>
• Bold !{Bold} → <b>Bold</b>
• Underline _{Underlined} → <u>Underlined</u>
• Code :{Code} → <span class="code">Code</span>
• CSS attributes

  ${attribute: value;attribute: value;(other css declaration...);
  (target contents)}

  → <div style="attribute: value;...">(target contents)</div>

Special markup

• Comments #{Comments} → Not included in the HTML
• Escaped brace \{ → {

Object floating markup

• Floating left of contents <{object name} → tag depends on object type but has class="left"
• Flowing along with contents @{object name} → tag depends on object type but has class="nofloat"
• Floating right of contents >{object name} → tag depends on object type but has class="right"

Hypertext links

• Picolisp Wiki internal resource ={Page Title} → <a href...>
• External resource ^{url Title} → <a href...>

Markup description

Structural markup

All the markup described in this section is converted into block HTML elements. A block element is always rendered on its own line and always flushes all the contents that follows it on a separate line.

• Headings
  
  n{Heading}
  
  Converted into an enclosing <hn> header tag, with n from 1 to 6, renders as a header of level n.
  
  For example: 4{My new header}

  My new header

• Unordered lists
  
  *{ ... }
  
  Converted into an enclosing <ul> tag, renders as an unordered list, with as many list items (<li>) as there are contained -{items}.

     *{
        -{unordered list item 1}
        -{unordered list item 2}
     }

  • unordered list item 1
  • unordered list item 2
• Ordered lists
  
  +{ ... }
  
  Converted into an enclosing <ol> tag, renders as an ordered list, with as many list items (<li>) as there are contained -{items}.

     +{
        -{ordered list item 1}
        -{ordered list item 2}
     }

  1. ordered list item 1
  2. ordered list item 2
• List item
  
  -{list item}
  
  Converted into a enclosing <li> tag, renders as a list item regardless of its position (inside or outside a list). If outside a list, renders as an orphan unordered list item.
  
  For example: -{orphan list item}

orphan list item

• Tables
  
  HTML tables with rows and cells can easily be created in wiki markup. Like lists, there is no internal control to check whether their structure is correct. The following markup is used:
  • Table
    
    %{table contents}
    
    Converted into an enclosing <table> tag with table contents composed of table rows
  • Table row
    
    ~{row content}
    
    Converted into an enclosing <tr> tag with row content composed of table cells
  • Table cell
    
    |{cell content}
    
    Converted into an enclosing <td> tag with cell content composed of arbitrary strings
  A table illustrating the above contents could look like this (with !{bold} markup added for the header row):

  %{
  ~{
  |{!{Meaning}}
  |{!{markup}}
  |{!{HTML}}
  }
  ~{
  |{Table frame}
  |{:{%{...}}}
  |{:{<table>...</table}}
  }
  ~{
  |{Table row}
  |{:{~{...}}}
  |{:{<tr>...</tr>}}
  }
  ~{
  |{Table cell}
  |{:{|{...}}}
  |{:{<td>...</td>}}
  }
  }
  

  And would be rendered like this:

  Meaning	markup	HTML
  Table frame	%{...}	<table>...</table
  Table row	~{...}	<tr>...</tr>
  Table cell	|{...}	<td>...</td>

• Preformatted text

  :{
     ...}

  Converted into an enclosing <pre> tag. All the white space (line breaks, tabs, spaces between words, etc.) is kept in the HTML rendering. This markup is mostly used to display pretty-printed code.
  
  Notice that the contents ( "..." here) starts on its own line. If the contents does not start on its own line, it will be "squashed" on one single line and will not be rendered as a block of its own. See :{code} below for a description of that feature.
  
  For example:

  :{
     'a
     '(a b)
     '(a . x)}

  Will be rendered this way:

     'a
     '(a b)
     '(a . x)

  But:

  :{ 'a
     '(a b)
     '(a . x)}

  Will be rendered as 'a '(a b) '(a . x).
• Line breaks
  
  
  • &{n}
    
    Converted into as as many <br/> as n, renders as line breaks.
  • &{-n}
    
    Converted into as as many <br/> as n, the first tag clears floating elements on its left and right side, renders as line breaks.
  • "natural" line breaks
    
    Natural line breaks entered with the "Return/Enter" key in the wiki source will be converted in pairs into sets of <br/><br/>. If one line break is missing to create a pair (odd number of line breaks), that line break will be ignored.
    
    If you need an odd number of line breaks, you must use the &{n} or &{-n} markup documented above.
    
    For example: [just one line break], not enough to create a pair, the line break is converted literally into a line break in the HTML and the rendering engine ignores it or renders it as a space between two strings. This line will thus render on the same line as "For example: ", but
    
    [two line breaks] with one pair of line breaks, this one will render on a separate paragraph,
    
    
    
    [five line breaks] while this one will render four lines below the above line, because the fifth line break was not enough to form a pair.

Appearance markup

All the markup described in this section is converted into inline HTML elements. An inline element is always rendered within a given line and never flushes contents that follows it on a separate line.

• Italic characters
  
  /{italic}
  
  Converted into an enclosing <i> tag, renders as an italic string.
• Bold characters
  
  !{bold}
  
  Converted into an enclosing <b> tag, renders as a bold string.
• Underlined characters
  
  _{underline}
  
  Converted into an enclosing <u> tag, renders as an underlined string.
• "code" strings
  
  :{code}
  
  Converted into an enclosing <span> tag. Notice that the :{ ... } syntax is similar to the <pre> markup above, but in this case the contents starts on the same line as the beginning of the markup: :{. Besides for this difference, the two styles are rendered similarly.
  
  For example:
  
  :{'(a b c)} is a list.
  
  will be rendered on one line, like this:
  
  '(a b c) is a list.
  
  Compare with:

  :{
  '(a b c)} is a list.

  which is rendered on two lines, like this:

  '(a b c)

  is a list.
• CSS attributes

  ${attribute: value;attribute: value;(other css declaration...);
  target text or markup on the next line}

  It is possible to add style to the text or tags. The various styles must be written on the same line, separated by a semicolon. The parsing stops at an horizontal tab, a line feed or a carriage return and at a closing brace.
  
  The markup is converted into an enclosing <div> tag that encapsulates the target contents and that contains the style attributes as inline style. Because of that, style added this way to an element cannot override style defined in the global style sheet for that element. See https://picolisp.com/wiki/wiki/wiki.css for the styles that applies to any element on the Picolisp wiki.
  
  The https://www.w3schools.com/cssref/ is an excellent CSS reference. As indicated above, not everything you'll try will work. If you see that an attribute that you set is not rendered the way you expect, check the syntax for trivial errors, check the global CSS file and the rendered syntax for conflicts.
  
  For example:

  ${border: red solid 1px;background-color: yellow;color:green;
  4{PicoLisp Documentation}}

  contains three style declarations that are converted into:

  <div style="border: red solid 1px;background-color:
  yellow;color:green;">
  <h4>PicoLisp Documentation</h4></div>

  and rendered this way:

  PicoLisp Documentation

  In this case, the color:green declaration is ignored because the global style sheet has a more specific declaration that sets the color of the <h4> tag to " MidnightBlue".
  
  Note that because the style is applied through the encapsulation of the contents inside a <div> block, the result will be a block. It is thus not possible to apply style partially to a line and keep that part within the line:

  The ${border: red solid 1px;background-color: yellow;color:green;
  PicoLisp Documentation} is very well written.

  will be converted into:

  The <div style="border: red solid 1px;background-color:
  yellow;color:green;">
  PicoLisp Documentation</div> is very well written.

  and rendered like this:
  
  The
  PicoLisp Documentation
  is very well written.
  
  Here, the "Picolisp Documentation" is not defined as a <h4> header but is just text. Since the global style sheet does not specify a color for normal text, the color:green; declaration can be applied. But since the style is applied through the creation of a <div> "capsule" around the string, that part will be displayed on its own line.

Special markup

• Comments
  
  #{comment}
  
  Not converted in the HTML. The contents of the comments is only /intended for the wiki source reader.
• Escaped brace
  
  \{
  
  The opening brace is a meta-character that indicates the beginning of some markup. If you need to display it on its own in a context where it could be interpreted as the beginning of some markup, you need to escape it to keep it from being interpreted.

Object floating

Objects that are uploaded to the wiki or referenced from other pages in the bottom part of the Edit window can be set to have floating contents on their sides or not.

The markup is converted into an object tag that depends on the object type:
• Image object example: <img src="path/to/object" alt="object name" class="left"/>
• Video object example: <video src="path/to/object" class="nofloat" preload="none" controls>object name</video>
The floating behavior depends on the object class: left, right or nofloat. See https://picolisp.com/wiki/wiki/wiki.css for the styles that apply to the various classes.
• Left floating object
  
  <{object name}
  
  Converted into a object tag with the class "left".
  
  The object will be floating on the left of the page and the contents that follows it will flow on its right side.


• Non floating object
  
  @{object name}
  
  Converted into a object tag with the class "nofloat".
  
  The object and the contents that follows it will be displayed "in flow" depending on their respective caracteristics.
• Right floating object
  
  >{object name}
  
  Converted into a object tag with the class "right".
  
  The contents will be floating on the right of the page and >the contents that follows it will flow on its left side.

Hypertext links

• Internal link
  
  ={Page Title}
  
  Converted into an enclosing <a href> anchor tag that points at a page in the wiki. "Title" is optional. "Page" is the short name of the page as found in the URL or the title of the page.
  
  For example: the page "Interfacing with Other Software" located at https://picolisp.com/53673/22551483888197633~?interfacing has "Picolisp Wiki: interfacing" for title. The "Page" element of the markup will be "interfacing".
  
  ={interfacing Interfacing with Other Software}
  
  Interfacing with Other Software
• External link
  
  ^{url Title}
  
  Converted into an enclosing <a href> anchor tag that points at a resource outside the wiki. "Title" is optional. "url" is the resource url.
  
  For example: the document "The Picolisp Reference" is located at https://software-lab.de/doc/ref.html.
  
  ^{https://software-lab.de/doc/ref.html The Picolisp Reference}
  
  The Picolisp Reference

Picolisp Wiki Mode for Emacs

In the lib/el/ folder of the PicoLisp distribution, the file picolisp-wiki-mode.el can be found. It is a major mode for GNU Emacs, written in Emacs Lisp, that makes writing and editing articles for the PicoLisp Wiki fast and convenient. All elements of the PicoLisp wiki syntax can be inserted by using easy keybindings. The mode offers fontification and outline-navigation too. To use it, you have to first load the file with M-x load-file and then put the buffer you want to edit in picolisp-wiki-mode with M-x picolisp-wiki-mode.

Usage

Keybindings for inserting are grouped by prefixes based on their function. For example, commands inserting links and lists begin with C-c C-l, those inserting floating content with C-c C-f, all other inserting commands with C-c C-c. The primary commands in each group are described below. You can obtain a list of all keybindings by pressing C-c C-h.

    ;; Element insertion
    "C-c C-l n" Insert Internal Link
    "C-c C-l x" Insert External Link
    "C-c C-l u" Insert Unordered List
    "C-c C-l o" Insert Ordered List
    "C-c C-l i" Insert List Item
    "C-c C-f l" Insert Left-Floating-Content
    "C-c C-f n" Insert Non-Floating Content
    "C-c C-f r" Insert Right-Floating-Content
    "C-c C-c k" Insert Line Breaks
    "C-c C-c 1" Insert Header 1
    "C-c C-c 2" Insert Header 2
    "C-c C-c 3" Insert Header 3
    "C-c C-c 4" Insert Header 4
    "C-c C-c 5" Insert Header 5
    "C-c C-c 6" Insert Header 6
    "C-c C-c b" Insert Bold
    "C-c C-c i" Insert Italic
    "C-c C-c u" Insert Underlined
    "C-c C-c p" Insert Pre Block
    "C-c C-c c" Insert Comment
    "C-c C-c -" Insert Horizontal Rule (hr)

    ;; Visibility cycling
    "<tab>" Picolisp Wiki Cycle
    "<S-iso-lefttab>" Picolisp Wiki Shifttab

    ;; Header navigation
    "C-M-n" Outline Next Visible Heading
    "C-M-p" Outline Previous Visible Heading
    "C-M-f" Outline Forward Same Level
    "C-M-b" Outline Backward Same Level
    "C-M-u" Outline Up Heading

Many of the commands described above behave differently depending on whether Transient Mark mode is enabled or not. When it makes sense, if Transient Mark mode is on and a region is active, the command applies to the text in the region (e.g., C-c C-c b makes the region bold). For users who prefer to work outside of Transient Mark mode, in Emacs 22 it can be enabled temporarily by pressing C-SPC C-SPC.

Outline Navigation

picolisp-wiki-mode supports outline-minor-mode as well as org-mode-style visibility cycling for PicoLisp Wiki style headers.

Navigation between headings is possible using outline-mode. Use C-M-n and C-M-p to move between the next and previous visible headings. Similarly, C-M-f and C-M-b move to the next and previous visible headings at the same level as the one at the point. Finally, C-M-u will move up to a lower-level (more inclusive) visible heading.

FIXME: Different header levels are not yet recognized by the outine commands.

Header visibility cycling

There are two types of visibility cycling: Pressing S-TAB cycles globally between the table of contents view (headers only), outline view (top-level headers only), and the full document view. Pressing TAB while the point is at a header will cycle through levels of visibility for the subtree: completely folded, visible children, and fully visible.

Fontification

picolisp-wiki-mode supports fontification of PicoLisp Wiki syntax and of text marked-up by the Wiki syntax.

FIXME: Due to the often nested structure of wiki-syntax elements, the regexp used to recognize different elements of a wiki-buffer are quite complicated and do not yet work reliably - thus fontification is still a bit random at the moment.

https://picolisp.com/wiki/?help

06sep21

brandelune